ReliefWeb API Frequently* Asked Questions

* In reality, some of these questions haven't been asked frequently, but are used as a way to make suggestions and pass on tips. Please let us know if you have any other questions or suggestions what would be helpful in this section.

How often is the data updated?

In real-time, every time content is added to ReliefWeb.

Back to TOC

How far does the data go back?

We have been posting Reports continuously since 1996 when ReliefWeb was launched. UN reports on major disasters from the 1980s are also available. We started carrying Jobs in 2001 and Training in 1998, but data is available only from 2011 onwards.

Back to TOC

What does "primary country" mean?

Please see the Fields tables section which also explains the meaning of the rest of the fields. For a detailed description of each value, please see the Taxonomy Descriptions page.

Back to TOC

How can I handle long GET queries?

GET queries are very useful for testing quickly from the browser, but with multiple parameters they can get unmanageably long. Some browsers have a limit on GET query length (at 2048 characters) and they become very difficult to read.

It is recommended to treat more complex queries as POST requests, use the verbose parameter to get the query in JSON syntax and paste it into any of the POST examples in this documentation for quick tests (checking the resource is correct in the url). (See also How do I convert GET requests to POST requests?. Also note that the search converter tool generates GET and POST queries from searches on ReliefWeb.

Back to TOC

How can I get exact results for my search terms?

Searching for "Myanmar: Earthquake" as the disaster.name will return results for "Myanmar:" plus "Earthquake". Using quotes can help here, as can the exact field qualifier. (Fields that can use exact are shown in the fields tables.) Note that in POST requests, as they are already quoted, this looks like "\"Myanmar: Earthquake\"" with 'escaped' quotes.

Compare:

All reports tagged with disasters including 'Myanmar:' or 'Earthquake' but not necessarily both at once

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&filter[field]=disaster.name&filter[value]=Myanmar: Earthquake&fields[include][]=disaster.name

All reports tagged with disasters including 'Myanmar: Earthquake' in their name

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&filter[field]=disaster.name&filter[value]="Myanmar: Earthquake"&fields[include][]=disaster.name

The same query written as a POST request:

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME
{
  "filter": {
    "field": "disaster.name",
    "value": "\"Myanmar: Earthquake\""
  },
  "fields": {
    "include": ["disaster.name"]
  }
}

All reports tagged with a disaster named exactly 'Myanmar: Earthquake' (there aren't any)

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&filter[field]=disaster.name.exact&filter[value]=Myanmar: Earthquake&fields[include][]=disaster.name

All reports tagged with a disaster named exactly 'Myanmar: Earthquake - Apr 2016'

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&filter[field]=disaster.name.exact&filter[value]=Myanmar: Earthquake - Apr 2016&fields[include][]=disaster.name
Back to TOC

How else can I refine a query to get better results?

For more complex queries, the API uses Lucene query parser syntax to deal with almost any combinations of search terms.

  • Boost

    As the default sort order for queries is relevance (see score), you can add extra weight to particular fields by adding ^ and a positive number to a field name.

    Compare:

    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&fields[include][]=source.name&query[fields][]=title^10&query[fields][]=source.name^1&query[value]=climate
    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&fields[include][]=source.name&query[fields][]=title^1&query[fields][]=source.name^10&query[value]=climate
  • Override the Operator

    AND, OR and NOT, within the value field, override the operator value.

    Compare:

    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&sort[]=date:desc&query[fields][]=title&query[value]=hot AND cold&query[operator]=OR
    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&sort[]=date:desc&query[fields][]=title&query[value]=hot OR cold&query[operator]=OR
    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&sort[]=date:desc&query[fields][]=title&query[value]=hot NOT cold&query[operator]=OR

    Note: we added sort[]=date:desc to these queries to show the difference. Otherwise, as they're sorted by relevance, results of AND and OR queries can look very similar.

    For more about the value syntax, see Boolean search operators in the Search help

  • Override the Query Fields

    As operator can be overridden by the value, so too fields. This allows targeting different fields with different terms. The syntax is fieldname:term.

    Compare:

    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&fields[include][]=source.name&query[value]=title:climate
    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&fields[include][]=source.name&query[value]=source:climate
  • Logical Groupings with Parentheses

    Logical groupings of search terms using parentheses give even more flexibility:

    https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&query[value]=("situation report" AND humanitarian) OR country:France
Back to TOC

How can I get just the total?

Each response has a 'totalCount' field, which shows the total number of matches for the query, not just the amount returned in the response, which is constrained by limit. If you only want to know the total, set the limit to 0 for a more concise response.

To find out how many reports have been published from IFRC, for example, look at the totalCount from:

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&filter[field]=source.shortname&filter[value]=IFRC&limit=0
Back to TOC

How do I convert POST requests to GET requests?

The short answer is you don't - but this explanation was written before this documentation had 'try it now' functionality and the idea was for testing API requests in the browser. Keeping it here in case it's helpful for interpreting GET request syntax.

This example query uses the fields, limit and preset parameters:

{
  "limit": 3,
  "preset": "latest",
  "fields": {
    "include": ["url"]
  }
}

Both limit and preset are simple keys and values, translating cleanly to limit=3&preset=latest but the fields paramater requires more thought (or copy and pasting - many times adapting the examples is quicker than starting from scratch). While strings or integers can be specified with only the = sign, objects and arrays need use of square brackets:fields[include][]=url.

Thus the GET query string becomes: limit=3&preset=latest&fields[include][]=url

If title was also an included field, the POST query would be:

{
  "limit": 3,
  "preset": "latest",
  "fields": {
    "include": ["url", "title"]
  }
}

and the GET query:limit=3&preset=latest&fields[include][]=url&fields[include][]=title

Nested values can also be tricky, for example, for the filter parameter. Take this example from earlier:

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME
{
  "filter":
  {
    "operator": "AND",
    "conditions":
      [
        {
          "field": "headline"
        },
        {
          "field": "country",
          "value": ["France"]
        }
      ]
  }
}

This involves four 'children' of the filter parameter, which each need to be specified individually.

The first is clear: 

filter[operator]=AND

The conditions must be separated with an arbitrary key. Starting from 0 is customary: 

filter[conditions][0][field]=headline

And the last shows the same conventions as the previous example - note how field, which requires a string, does not have [] at the end of the key, while value which requires an array, must be followed by []: 

filter[conditions][1][field]=country&filter[conditions][1][value][]=France

So the GET query is:

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&filter[operator]=AND&filter[conditions][0][field]=headline&filter[conditions][1][field]=country&filter[conditions][1][value][]=France

Use the verbose parameter to check the conversion.

https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&verbose=1&filter[operator]=AND&filter[conditions][0][field]=headline&filter[conditions][1][field]=country&filter[conditions][1][value][]=France
Back to TOC

How do I convert GET requests to POST requests?

The verbose parameter is included to help with this. Add verbose=1 to a GET request and the equivalent JSON will be shown in the response.

Back to TOC

Are client libraries available?

Yes, there are very simple client libraries for PHP and Golang. Please use them!

Back to TOC