# Cards

MapaKalamidad report cards for disaster events. Note: [authentication](https://docs.petabencana.id/general/authentication.html) is required to make updates to cards.

## Request Format

| URL Parameter | Description                                                                                                                     | Format                      | Required |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------- |
| cardId        | Unique identifier of the card we wish to work with, this is generated by the system when the initial card is created (required) | String (7 to 14 characters) | Yes      |

| Attribute   | Description                               | Format                                                                | Required |
| ----------- | ----------------------------------------- | --------------------------------------------------------------------- | -------- |
| card\_data  | User data collected in card interface     | JSON                                                                  | Yes      |
| text        | Description of the disaster event         | String                                                                | No       |
| image\_id   | Identifier of the associated card image   | String                                                                | No       |
| created\_at | Date and time the card was created        | Date ([ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm))  | Yes      |
| location    | Geographic location of the disaster event | Lat/Long in [ESPG:4326](http://spatialreference.org/ref/epsg/wgs-84/) | Yes      |

### Note on card\_data

Card data requires the object `report_type` to exist. Where `disaster_type` is set to 'flood' then the object `flood_depth` should also exist adjacent to `report_type`. Where the `disaster_type` is 'prep' then `report_type` should be one of the types as specified in server config.js.

| Disaster Type | report\_type | Attribute details                                                                                                                                                                                                                                           |
| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Flood         | flood        | <p>flood\_depth: flood severity based on depth in cm<br></p><p>< 70 cm : Minor</p><p>70 - 150 cm : Moderate</p><p>150 cm : Severe</p>                                                                                                                       |
| Earthquake    | road         | <p>accessabilityFailure: the level of road damage affected by earthquake<br><br>0 : < 0,5 m (No Vehicle Access)<br>1 : 0,6 - 1 m (2 and 3-Wheel Vehicle)<br>2 or 3 : 1.1 - 1.8 m (4-Wheel Vehicle)<br>4 : >1,9 m Large Vehicles (Large SUVs and Trucks)</p> |
| Earthquake    | structure    | <p>structureFailure: the level of structure damage affected by earthquake</p><p>0 : Observed Shaking<br>1 : Minor Damage<br>2 : Major Damage<br>3 : Fully Collapsed</p>                                                                                     |
| Volcano       | volcanic     | <p>volcanicSigns: Volcano Observations</p><p>0 : Water Sources are drying up/Contaminated<br>1 : Declining plant health<br>2 : Unusual Animal Behaviour<br>3 : Frequent Earthquake Tremors<br>4 : Frequent Rumbling Sounds</p>                              |
| Volcano       | ashfall      | <p>smogImpact: the level of ashfall situation</p><p>0 : Fine/Dry<br>1 : Granulated<br>2 : Dense/Wet</p>                                                                                                                                                     |
| Typhoon       | wind         | <p>impact: level of disruption caused by extreme wind</p><p>0 : Low Disruption<br>1 : Medium Disruption<br>2 : High Disruption</p>                                                                                                                          |
| Typhoon       | flood        | <p>flood\_depth: flood severity based on depth in cm<br></p><p>< 70 cm : Minor</p><p>70 - 150 cm : Moderate</p><p>150 cm : Severe</p>                                                                                                                       |
| Typhoon       | storm        | <p>impact: Disruption Levels<br></p><p>Low</p><p>Medium</p><p>High</p>                                                                                                                                                                                      |

For example a card with flood data including flood\_depth:

```javascript
  "disaster_type": "flood",
  "card_data":{
    "report_type": "flood",
    "flood_depth": 50
  }
```

## GET /cards/:cardId

Retrieve details of a card:

Here is a simple call to GET a card:

```
curl -X GET -H "X-Api-Key: API_KEY_GOES_HERE" "https://data.mapakalamidad.ph/cards/abcdefg"
```

The card was found:

```javascript
{
  "statusCode": 200,
  "result": {
    "pkey": "2",
    "card_id": "abcdefg",
    "username": "user",
    "network": "test",
    "language": "en",
    "received": true,
    "report_id": "1"
  }
}
```

The card does not exist:

```javascript
{
  "statusCode": 404,
  "found": false,
  "result": null
}
```

## PUT /cards/:cardId

Update a card with details a disaster event report:

Here is a simple call to PUT a card:

```
curl -X PUT -H "X-Api-Key: API_KEY_GOES_HERE" -d '{
    "text": "test card",
    "disaster_type": "flood"
    "card_data":
      {
        "report_type": "flood",
        "flood_depth": 101
      },
    "created_at":"2016-12-09T11:32:52.011Z",
    "location": {
        "lat": -6.149531,
        "lng": 106.869342
    }
}' "https://data.mapakalamidad.ph/cards/abcdefg"
```

Card was successfully created:

```javascript
{
  "statusCode": 200,
  "cardId": "abcdefg",
  "created": true
}
```

The card does not exist:

```javascript
{
  "statusCode": 404,
  "cardId": "abcdefg",
  "message": "No card exists with id 'abcdefg'"
}
```

The report already exists for the card:

```javascript
{
  "statusCode": 409,
  "cardId": "abcdefg",
  "message": "Report already received for card 'abcdefg'"
}
```

## GET /cards/:cardId/images

GET a signed S3 URL to upload a card report, this must be done after the card report has been created and only one image can exist for a given card.

NOTE: After an image is submitted a server-side process shrinks the image to a standard size and there may be a small time lag of a few seconds before the image goes "live".

Here is a simple call to GET a new signed S3 URL for image upload:

```
curl -X GET \
  https://api-server-dev.riskmap.in/cards/HJID8CWN-/images
```

Signed S3 URL successfully generated:

```javascript
{"signedRequest":"https://riskmap-image-uploads.s3.ap-south-1.amazonaws.com/originals/BJbTHR-Vb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJFMR3NR7BXZ5X7DA%2F20170629%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20170629T012002Z&X-Amz-Expires=900&X-Amz-Signature=ad10a53555205fa18ecfa07da52eb0349ed1c8bda66fe2de0fa9c445c61b7c62&X-Amz-SignedHeaders=host","url":"https://s3.ap-south-1.amazonaws.com/riskmap-image-uploads/originals/BJbTHR-Vb.jpg"}
```