# Cards
Petabencana 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 | flood\_depth: flood severity based on depth in cm
< 70 cm : Minor
70 - 150 cm : Moderate
150 cm : Severe
|
| Earthquake | road | accessabilityFailure: the level of road damage affected by earthquake
0 : < 0,5 m (No Vehicle Access)
1 : 0,6 - 1 m (2-Wheel Vehicle Access)
2 or 3 : 1.1 - 1.8 m (4-Wheel Vehicle Access)
4 : >1,9 m (Large Vehicle Access)
|
| Earthquake | structure | structureFailure: the level of structure damage affected by earthquake
0 : Cracking
1 : Partially Collapse
2 : Fully Collapse
|
| Extreme Wind | wind | impact: level of disruption caused by extreme wind
0 : Low Disruption
1 : Medium Disruption
2 : High Disruption
|
| Haze | haze | visibility: the distance one can see as determined by light and weather conditions
0: can see but need to wear a mask
1: can see but not clean enough to drive
2: can barely see, too dangerous to go out
airQuality: described by symptoms felt by humans
0 or 1: Poor Air Quality
2: Severe Air Quality
3 or 4 : Hazardous Air Quality
|
| Forest Fire | fire | **fireRadius**: the radius of a forest fire estimated by the human eye |
For example a card with flood data including flood\_depth:
```javascript
"disaster_type": "flood",
"card_data":{
"report_type": "flood",
"flood_depth": 50
}
```
Or, a card with pre-flood data report regarding a drain.
```javascript
"disaster_type": "prep",
"card_data":{
"report_type":"drain"
}
```
## 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.petabencana.id/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.petabencana.id/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"}
```