Skip to content

API Documentation

Jump to bottom
Hussein Al-Olimat edited this page Dec 17, 2018 · 6 revisions

Introduction

DisasterRecord API lets you retrieve data about help seekers and first responders during natural disaster events. The data is retrieved based on a list of parameters such as time, distance range, and current location, of a help seeker or a first responder. The full list of parameters are described in more details in the next section.

The response body is defined with URL parameters sent through a standard HTTP request and is returned as a JSON object.

Sample request using the demo API key (for demo purposes, this request always returns the same result):

http://hazardsees.knoesis.org:8085/disaster_record/api?campaign=chennai&user=individual&request=rescue&time=1471677320000&lat=13.0529181&lon=80.2039631&radius=5000&key=8c32d1183251df9828f929b935ae0419

sample response:

{
    "Matches": [
        {
            "status": "available",
            "OSM_feature": {
                "value": "hospital",
                "key": "amenity",
                "icon": "https://wiki.openstreetmap.org/w/images/thumb/2/22/Hospital-16.svg/32px-Hospital-16.svg.png"
            },
            "name": "Right Hospitals",
            "destination": {
                "type": "Point",
                "coordinates": [
                    80.2405731,
                    13.0787952
                ]
            },
            "class": "rescue_match",
            "other_info": ""
        }
    ],
    "request": {
        "time_of_the_request": "1471677320000",
        "type": "rescue_match",
        "user": "individual",
        "coordinates": [
            13.0529181,
            80.2039631
        ]
    }
}

Before you begin

Make sure you have a valid API key, which you can request from here.

Definitions

  • First responder - a person who is among the first to arrive and provide assistance at the event of natural disasters. Wikipedia
  • Help seeker - a person who is seeking assistance during the event of a natural disaster. Those affected individuals might reach out to the nearby places in hope to fulfill health-related needs, rescue needs, or supplies needs.

In general, as you will see later, all requests and corresponding responses can be divided into two groups. The first group includes all requests made by help seekers to receive information about the available locations that can provide help. The second group consists of all requests made by first responders, where the response contains information about individual help requests that first-responders can reach out and respond to.

URL Parameters

DisasterRecord API request is an HTTP URL of the following form:

http://hazardsees.knoesis.org:8085/disaster_record/api?parameters

As is a standard in URLs, all parameters are separated using the ampersand (&) character. The parameters and examples of their possible values and units are described below:

  • campaign - a predefined natural disaster event id. The full list of possible values can be found by issuing the following HTTP request to DisasterRecord API link goes here

  • user - a parameter that must be a text string and have a value of either individual or responder. If the value passed here is individual then the response data gives information about all places that are able to provide help for help seekers. If the parameter's value is responder then the response provides information about all help seekers.

  • request - a parameter that must be a text string and have value either rescue or shelter. The output data specified by this parameter is affected by the user parameter also.

    • As a responder user -
      • if the parameter value is rescue then the API returns the needs related to death reports, Missing, trapped, injured, dead, affected, or found people that require rescue/health/medical help.
      • if the parameter value is shelter then the API returns the needs related to donations, volunteering services, displaced people, evacuations that require shelter/food/supplies help.
    • As an individual user -
      • if the parameter value is rescue then the API returns the available locations providing rescue/health/medical help.
      • if the parameter value is shelter then the API returns the available locations providing shelter/food/supplies help.

  • key - a parameter that must be a text string and is an API key provided to you

  • time - specifies the time of the request represented as an integer number in Unix Epoch Time

  • time_delta - specifies a time range used to filter the stream of data from the time of the API request. For example, choosing to get only the data which were posted in Twitter in the last 60 minutes. If not specified, the default value is 120 (minutes)

  • radius - specifies the radius range from the users's location in order to return only the data which are within the specified distance. The parameter value is an integer number in meters. If not specified, the default value is 5000 (meters)

  • lat - specifies the latitude of the user as a floating point value

  • lon - specifies the longitude of the user as a floating point value

First responder request

First responder HTTP request requires the following list of parameters in any order:

  • campaign
  • user
  • request
  • key
  • time
  • time_delta
  • radius
  • lat
  • lon

Example requests:

  • http://hazardsees.knoesis.org:8085/disaster_record/api?campaign=chennai&time=1471677320000&time_delta=180&lat=12.9461192&lon=80.1387107&radius=5000&user=responder&request=shelter&key=YOUR_API_KEY

    The above API call would only return needs related to donations, volunteering services, displaced people, evacuations and individuals who require shelter/food/supplies help, which are within a 5000m radius from the user's location (i.e., lat=12.9461192, lon=80.1387107), and within the last 180 minutes from the API call time (i.e., 1471677320000).

  • http://hazardsees.knoesis.org:8085/disaster_record/api?campaign=chennai&time=1471677320000&time_delta=240&lat=12.9461192&lon=80.1387107&radius=2000&user=responder&request=rescue&key=YOUR_API_KEY

    The above API call would only return needs related to death reports, missing, trapped, injured, dead, affected, or found people who require rescue/health/medical help, which are within a 2000m radius from the user's location (i.e., lat=12.9461192, lon=80.1387107), and within the last 240 minutes from the API call time (i.e., 1471677320000).

Help seeker request

Help seeker HTTP request requires the following list of parameters in any order:

  • campaign
  • user
  • request
  • key
  • time
  • radius
  • lat
  • lon

Examples:

  • http://hazardsees.knoesis.org:8085/disaster_record/api?campaign=chennai&time=1471677320000&lat=13.0529181&lon=80.2039631&radius=5000&user=individual&request=rescue&key=YOUR_API_KEY\

    The above API call would only return available locations providing rescue/health/medical help, which are within a 5000m radius from the user's location (i.e., lat=12.9461192, lon=80.1387107).

  • http://hazardsees.knoesis.org:8085/disaster_record/api?campaign=chennai&time=1471677320000&lat=13.0529181&lon=80.2039631&radius=5000&user=individual&request=shelter&key=YOUR_API_KEY\

    The above API call would only return available locations providing shelter/food/supplies help, which are within a 5000m radius from the user's location (i.e., lat=12.9461192, lon=80.1387107).

JSON response

This section describes the structure of the API responses returned as JSON objects and provides examples of requests made by either a first responder or a help seeker

In general, a json response has the following structure:

{
  "Matches": [],
  "request": {
    "time_of_the_request": "1471677320000",
    "type": "shelter_matching",
    "user": "responder",
    "coordinates": [
      12.9461192,
      80.1387107
    ]
  }
}
  • request key contains information about the user who issued a request
    • time_of_the_request key is the time of the request passed as a part of the HTTP request
    • type is the request type that corresponds to a request parameter
    • user is the user type that corresponds to a user parameter
    • coordinates is a JSON array that contains two values lat and lon to represent coordinates of the user issuing the request
  • Matches JSON array contains information about either locations, which are able to provide help in disaster recovery or people who seek help based on user parameter. Important: matches array can be empty if no matches have been found based on the provided search parameters.
    • First responder matches: Each element of array is enclosed in {} and has the following keys if the request is issued by a first responder:
      • text is the text message of the tweet posted by a help seeker
      • created_at is the time when the tweet was created in milliseconds
      • destination is the location of the help seeker
      • flood is an indication if the location of the help seeker is flooded or not (true or false)
      • match_icon contains a link to an icon that can be displayed as an indicator of the location of the help seeker
      • class is the help seeker's class that corresponds to the request parameter. Possible values: shelter_matching or rescue_match
      • images is the JSON array that contains more information about the help seeker: number of people, animals, vehicles, presence, existence of drinking water (see example below). Important: images array can be empty
    • Help seekers matches: Each element of array is enclosed in {} and has the following keys if the request is issued by a help seeker:
      • status represents the availability of the location, which can provide help
      • OSM_feature describes the location's type and provides a link to an icon that depicts the location
      • name is the name of the location
      • destination is the coordinates of the location
      • class is the class type of the location that depends on the request parameter. Possible values: shelter_matching or rescue_match
      • other_info includes other information about the location

First responder response examples:

{
  "Matches": [
    {
      "text": "RT @ArunkumarR: #URGENT #CHENNAI: 15 units of A1B+ blood needed at Global hosp Chennai by tmrw morning. Cont: Arun +9190032 77770 @Chinmayi...",
      "created_at": 1452097982000,
      "destination": {
        "type": "Point",
        "coordinates": [
          80.1387107,
          12.9461192
        ]
      },
      "flood": false,
      "match_icon": "https://github.com/shrutikar/DisasterRecord/blob/CFC/static/shelter_need.png",
      "images": [{"water": true, "objects": {"person":"5", "dogs": "1", "vehicles": "0"}, "imageURL": url}],
      "class": "shelter_matching"
    }
  ],
  "request": {
    "time_of_the_request": "1471677320000",
    "type": "shelter_matching",
    "user": "responder",
    "coordinates": [
      12.9461192,
      80.1387107
    ]
  }
}
{
  "Matches": [
    {
      "text": "RT @ArunkumarR: #URGENT #CHENNAI: 15 units of A1B+ blood needed at Global hosp Chennai by tmrw morning. Cont: Arun +9190032 77770 @Chinmayi...",
      "created_at": 1452097982000,
      "destination": {
        "type": "Point",
        "coordinates": [
          80.1387107,
          12.9461192
        ]
      },
      "flood": false,
      "match_icon": "https://github.com/shrutikar/DisasterRecord/blob/CFC/static/shelter_need.png",
      "images": [{"water": false, "objects": {"person":"5", "dogs": "1", "vehicles": "0"}, "imageURL": url}],
      "class": "rescue_match"
    }
  ],
  "request": {
    "time_of_the_request": "1471677320000",
    "type": "rescue_match",
    "user": "responder",
    "coordinates": [
      12.9461192,
      80.1387107
    ]
  }
}

Help seeker response examples:

{
  "Matches": [
    {
      "status": "available",
      "OSM_feature": {
        "value": "hospital",
        "key": "amenity",
        "icon": "https://wiki.openstreetmap.org/w/images/thumb/2/22/Hospital-16.svg/32px-Hospital-16.svg.png"
      },
      "name": "Right Hospitals",
      "destination": {
        "type": "Point",
        "coordinates": [
          80.2405731,
          13.0787952
        ]
      },
      "class": "rescue_match",
      "other_info": ""
    }
  ],
  "request": {
    "time_of_the_request": "1471677320000",
    "type": "rescue_match",
    "user": "individual",
    "coordinates": [
      13.0529181,
      80.2039631
    ]
  }
}
{
  "Matches": [
    {
      "status": "available",
      "OSM_feature": {
        "value": "hospital",
        "key": "amenity",
        "icon": "https://wiki.openstreetmap.org/w/images/thumb/2/22/Hospital-16.svg/32px-Hospital-16.svg.png"
      },
      "name": "Right Hospitals",
      "destination": {
        "type": "Point",
        "coordinates": [
          80.2405731,
          13.0787952
        ]
      },
      "class": "shelter_matching",
      "other_info": ""
    }
  ],
  "request": {
    "time_of_the_request": "1471677320000",
    "type": "shelter_matching",
    "user": "individual",
    "coordinates": [
      13.0529181,
      80.2039631
    ]
  }
}

Errors

  • DisasterRecord API will return an error message as a JSON object if the HTTP request is constructed in inappropriate format or if the parameters are provided using a wrong data type.

    {"message": "Internal Server Error"}

  • The authorization error indicates that your API key is not valid or missing from the list of parameters passed as a part of the URL:

    {"message": 'Authorization Error'}

  • The incorrect user type error indicates that provided value for the user parameter is invalid

    {"message": "Incorrect User Type"}

  • The incorrect request type error indicates that provided value for the request parameter is invalid

    {"message": "Incorrect Request Type"}

Clone this wiki locally