ReliefWeb API Result structure

Structure of a successful result

Result body comes as a json object with the following fields:

  • href: Url of the current request - POST request bodies aren't reflected here.
  • time: Milliseconds taken to calculate the response.
  • links: HAL-type links to previous and next resources, for lists, or to collection for items.
    • self: Current request.
    • next: Next page of results in list. Previous link also shown when appropriate.
  • totalCount: Total number of results that match the request. See How can I get just the total?
  • count: Number of results returned in this result.
  • data: All the requested items:
    • id Unique ReliefWeb id for the item (for items and lists). Ids can be used to find the resource directly on the ReliefWeb site.
      For reports, jobs and training: http://reliefweb.int/node/<id>
      For countries, disasters, sources, and some category fields with an id: http://reliefweb.int/taxonomy/term/<id>
    • fields Fields returned for this result. These can be selected by specifying fields, profile and preset parameters (for items and lists).
    • score Relevance of result to query. If there was no query parameter, this will be 1 (for lists only).
    • href Url of the resource item. Useful for drilling down into individual results (for lists only).

Example:

  • Query:

    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&profile=full&limit=1

Structure of an error

The message of an error should give information to fix the request. Again, for clarification or suggested improvements, please contact us.

  • Invalid "limit" specified. Valid values are between 0 and 1000

    In the example, change 5000 to fix this.

    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&limit=5000

  • Invalid range 'from' value for field 'date.created'. It must be an ISO 8601 date.

    In this example, the date field is non url-encoded. To fix it, replace the + sign to %2B.

    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&filter[field]=date.created&filter[value][from]=2004-06-01T00:00:00+00:00

  • Invalid query field 'field'. Valid values are 'value', 'operator', 'fields'.

    In this example, there are two errors.

    • The wrong key is used for the query parameter. Replace query[field] with query[fields] to fix it.
    • This exposes another error, that query[fields] expects an array. To fix that error: query[fields][]=country.
    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&query[field]=country&query[value]=France