ReliefWeb API Documentation

Introduction

The ReliefWeb API was built to power a mobile/ low-bandwidth version of the ReliefWeb website. Since then it has been enhanced for a public release to provide access to ReliefWeb's curated and continuously updated data archive. It's now used to serve much of the main site, selected content on other OCHA sites, and third party apps.

All the content of ReliefWeb is available through its API. The API is built to fit with current API best-practices, and is intended to be friendly to developers, as well as machines. It is publicly accessible using HTTP requests and returns JSON data.

Understanding the structure of ReliefWeb's content will help in understanding how the API works, so these documents are intended to make both as clear as possible. For clarification or to suggest improvements, please contact us.

Quickstart

api-query search-options

As the 'rivers' pages (updates, disasters, jobs, etc.) use the API too, they are the quickest way to get started with queries and filters.

Use the filters and the search bar to refine the query - with 'Search Options', as in the screenshot, for more complex queries.

The API query button will launch the search converter tool to transform the url into an API query, showing both the GET URL and the JSON payload for a POST request.

Versions

The current version is version 1, abbreviated as v1. The previous version, v0, is deprecated and should no longer be used.

Using the API

The API is read-only. It is called using an HTTP URL. The query is handled differently for GET and POST requests, the scheme, host and path are the same for both:

Scheme:
"https://"
Host:
"api.reliefweb.int"
Path:
"/v1/" <content type> [ "/" <content id> ] "?appname=" <your-app-name>
Parameters:

Parameters can be passed in the query of a GET request:

https://api.reliefweb.int/v1/reports?appname=apidoc&limit=2

or as a body to a POST request:

https://api.reliefweb.int/v1/reports?appname=apidoc
{
  "limit": 2
}

There are very simple client libraries for PHP and Go. Please use them!

GET requests can be made directly in a browser. To view the results more clearly, consider using an extension:

Post requests can be made via the editable textboxes in this documentation, or, from a command line, with a tool like curl:

curl -POST 'https://api.reliefweb.int/v1/reports' -d '{"limit": 2}'

When dealing with JSON format for the post requests, a misplaced comma can be difficult to spot. To troubleshoot the error Invalid request body. It must be a valid json object., validators like JSONlint can save a lot of time.

Using the documentation

All examples in this documentation can be edited in place and tested against the API using the 'Try it out' button.

The API is also documented in line with version 2.0 of the OpenAPI Specification (also known as Swagger). The definition is at http://apidoc.rwlabs.org/swagger.yaml and you can explore this by pasting that URL into the Swagger UI demo: http://petstore.swagger.io/

There is also a forum for questions and discussion at groups.google.com

Endpoints

There are seven types of content available through the API, each with a dedicated endpoint. reports, disasters, countries, jobs, training, sources and references.

  • reports - The main content of ReliefWeb. Reports are updates and analysis curated from more than 4,000 sources and tagged by our team of editors working around the clock.
  • disasters - A key function of the site is to group reports together by disaster. This disaster metadata is essential for providing overviews of situations and for finding related content.
  • countries - ReliefWeb's information about countries. Shows how ReliefWeb groups information by geographical locations.
  • jobs - The place to advertise or find humanitarian jobs. Jobs are classified by type, category, location and requirements and all are made available through the API.
  • training - A growing section of the site. Training opportunities and courses for useful and necessary humanitarian skills. (Note that unlike the other content types, there's no 's' on 'training')
  • sources - Our partners. ReliefWeb's role is to collect, curate and deliver timely humanitarian information. This information comes from a wide range of trusted sources. Information about those sources, and their reports, is available here.
  • references - Our taxonomy. ReliefWeb's editorial team tag content with to make it easier to organize and find specific content. These are detailed here to make so they can be more transparently matched with vocabularies used by other organizations.

Lists and items

There are two main types of request list and item:

  • List requests - without a content id.

    Almost all of the documentation concerns these requests, as there are many possibilities to refine the request to dig for information.

    Note: all parameters can be used with list requests.

    Examples:

    • Show reports (by default, the latest 10):

      GET:

      https://api.reliefweb.int/v1/reports?appname=apidoc

      POST:

      https://api.reliefweb.int/v1/reports?appname=apidoc
      {
      }
      
  • Item requests - with a content id.

    These are to find more details on a specific piece of content based its the ReliefWeb id. You would usually have to find the id through a list request.

    Note: only the fields and profile parameters can be used with item requests.

    Examples:

    • Information about the report with id 1082221:

      GET:

      https://api.reliefweb.int/v1/reports/1082221?appname=apidoc&fields[include][]=source.name

      Note: As the parameters are much easier to handle, item requests are only possible with GET requests.

Request parameters

Appname

(string) This parameter allows ReliefWeb to monitor API usage and adapt it to user needs.

Please use your website url if you have one or an email address where we can contact you. All of the examples in this documentation use apidoc but if you copy and paste examples into your own applications, we ask you to change it.

Note that for both GET and POST requests, the appname parameter is sent in the url.

If you rely on the API, do let us know through the contact form, so we can keep you informed of any changes.

Query

(array) This is equivalent to the search box.

search box

The query field has many shorthand properties, see the tips section for more details.

Queries are made of three parts: value, fields and operator.

  • value (string): What to search for. Required for all queries.
  • fields (array): Which fields to query on. See fields tables for options.
  • operator (string): How to interpret spaces in the query. Can be AND or OR. Default value is OR.

Examples:

  • Query for a word or phrase. Here, looking for 'earthquake'. value

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&query[value]=earthquake

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "earthquake"
        }
    }
    
  • Query for a word or phrase occuring in a limited number of fields. Here, looking for sources with 'earthquake' in their name.

    Note: for searching in a single field, query[value]=<field>:<value> is more concise. Using query[fields] is useful when limiting the search to a number of fields. value, fields

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&query[value]=earthquake&query[fields][]=source&fields[include][]=source.name

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "earthquake",
          "fields": ["source"]
        },
      "fields":
        {
          "include": ["source.name"]
        }
    }
    
  • Query for all specified words. This example looks for titles with the words 'hot' AND 'cold'. Try editing the call, removing the operator parameter or using 'OR' instead of 'AND', and compare the results. ('OR' is the default value for operator.) value, fields, operator

    Note: because results are ordered by relevance (see the result field Score), the results for AND and OR can be almost identical. We have used preset=latest to make the difference more explicit. We could also have used sort[]=date:desc.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&query[fields][]=title&query[value]=hot cold&query[operator]=AND&preset=latest

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "hot cold",
          "fields": ["title"],
          "operator": "AND"
        },
      "preset": "latest"
    }
    
  • Query for exact values. Some fields (shown in fields tables with the exact attribute) use the qualifier .exact to limit the search. Compare this search with and without using .exact. This can also be used with the filter parameter. value, fields

    Note: for more complex queries, the API uses Lucene query parser syntax to deal with almost any combinations of search terms. See also Getting exact results and Advanced use of the query field in the tips and examples section.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&query[fields][]=source.shortname.exact&query[value]=UN&fields[include][]=source.shortname

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "UN",
          "fields": ["source.shortname.exact"]
        },
      "fields":
        {
          "include": ["source.shortname"]
        }
    }
    

Filter

(array) Filters narrow down the content to be searched in. These correspond to the 'Search options' box under the search bar.

search options

Filters are made up of five parts: field, value, operator, negate and conditions.

  • field (string): Which field to filter on. See fields tables
  • value (boolean | integer | string | array): Most of the possible values are pre-defined. If this is for a date, or numeric value (e.g. id), it can be a range defined by from and to values. If only from or to is present, then value will match those greater than or equal to or less than or equal to the value respectively. If value is missing, the filter will act on whether the field exists or not.
  • operator (string): How to combine filter array values or conditions. Can be AND or OR.
  • negate (boolean): true will select all items that do not match the filter.
  • conditions (array): Used to combine multiple filters.

Examples:

  • Filter by whether a field has a value or not. This returns reports with headlines. field

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[field]=headline

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "field": "headline"
        }
    }
    
  • Filter by whether a field has a particular value. This returns reports tagged with France. value, field

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[field]=country&filter[value]=France

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "field": "country",
          "value": "France"
        }
    }
    
  • Filter by whether a field has one of a range of values. This returns reports tagged with France or Spain. value, field, operator

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[field]=country&filter[value][]=Spain&filter[value][]=France&filter[operator]=OR

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "field": "country",
          "value": ["France", "Spain"],
          "operator": "OR"
        }
    }
    
  • Filter to exclude some values. This returns reports tagged with France or Spain but not Italy. value, field, operator, conditions, negate

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[operator]=AND&filter[conditions][0][field]=country&filter[conditions][0][value][]=Spain&filter[conditions][0][value][]=France&filter[conditions][0][operator]=OR&filter[conditions][1][field]=country&filter[conditions][1][value]=Italy&filter[conditions][1][negate]=true

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "operator": "AND",
          "conditions": [
            {
              "field": "country",
              "value": ["France", "Spain"],
              "operator": "OR"
            },
            {
              "field": "country",
              "value": "Italy",
              "negate": true
            }
          ]
        }
    }
    
  • Filter by a range of values - dates or numbers. This gets reports from June 2004. field, value from, value to

    Note: Dates must be URL-encoded for GET requests, but not for post requests. + should be written as %2B.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[field]=date.created&filter[value][from]=2004-06-01T00:00:00%2B00:00&filter[value][to]=2004-06-30T23:59:59%2B00:00

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "field": "date.created",
          "value":
            {
              "from": "2004-06-01T00:00:00+00:00",
              "to": "2004-06-30T23:59:59+00:00"
            }
        }
    }
    
  • Filter by multiple conditions. This combines two earlier examples, getting reports tagged with France that also have headlines. value, field, operator, conditions

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[operator]=AND&filter[conditions][0][field]=headline&filter[conditions][1][field]=country&filter[conditions][1][value]=France

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "operator": "AND",
          "conditions": [
            {
              "field": "headline"
            },
            {
              "field": "country",
              "value": "France"
            }
          ]
        }
    }
    
  • Filter by multiple, nested conditions. With more than a couple of filters, it's easier to read the JSON body of a POST query than the GET url. This esample returns Maps or Infographics for Afghanistan and any reports with headlines. value, field, operator, conditions

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[operator]=OR&filter[conditions][0][operator]=AND&filter[conditions][0][conditions][0][field]=primary_country&filter[conditions][0][conditions][0][value]=Afghanistan&filter[conditions][0][conditions][1][operator]=OR&filter[conditions][0][conditions][1][field]=format&filter[conditions][0][conditions][1][value][]=Map&filter[conditions][0][conditions][1][value][]=Infographic&filter[conditions][1][field]=headline&fields[include][]=format.name&fields[include][]=primary_country.name&fields[include][]=headline.title

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "operator": "OR",
          "conditions":
            [
              {
                "operator": "AND",
                "conditions":
                  [
                    {
                      "field": "primary_country.name",
                      "value": "Afghanistan"
                    },
                    {
                      "operator": "OR",
                      "conditions":
                        [
                          {
                            "field": "format.name",
                            "value": ["Map", "Infographic"]
                          }
                        ]
                    }
                  ]
              }
            ],
          "conditions":
            [
              {
                "field": "headline"
              }
            ]
        },
      "fields":
        {
          "include":
            [
              "headline.title",
              "format.name",
              "primary_country.name"
            ]
        }
    }
    

Facet

facets

(array) Facets are used on the ReliefWeb site to show a set of contents split by categories, status and/or date, and their frequencies. These allow for broad-ranging queries, which would otherwise involve many individual requests. These are shown on the site to allow a quick way to drill down into the results.

Facets are made up of seven parts: field, name, limit, sort, filter, interval and scope.

  • field (string): which field to create facets for. These may be dates, categories or the status field. See fields tables
  • name (string): A label for this facet. Useful for when faceting multiple ways over the same field.
  • limit (integer): The number of facets to return for non-date based facets. Defaults to 10.
  • sort (string): The sort order of non-date facets, by value or count of terms (e.g. countries can be ordered alphabetically or with the most represented first, or last). In the form of {type:direction} where type is count or value and direction is asc or desc. Defaults to count:desc.
  • filter (array): See filter parameters - these can be applied to facets.
  • interval (string): For date facets, break down into year, month, week or day.
  • scope (string): global or query. Whether the facet is filtered by the query or globally.

Examples:

Note: In the following examples we're using limit=0, as we're only interested in the facets themselves.

  • Get the most common categories for a given field. This lists the top countries with the highest number of jobs and the number of jobs for each. field, limit

    This is also useful for getting all available categories for some fields. For example, try swapping 'theme' for 'country' to get a list of all the themes ReliefWeb uses for tagging jobs.

    GET:

    https://api.reliefweb.int/v1/jobs?appname=apidoc&facets[0][field]=country&facets[0][limit]=20&limit=0

    POST:

    https://api.reliefweb.int/v1/jobs?appname=apidoc
    {
      "facets": [
        {
          "field": "country",
          "limit": 20
        }
      ],
      "limit": 0
    }
    
  • Use sort to change the order. This gets the 10 countries with fewest reports, and the number of reports for each. (10 is the default limit for facets). field, sort

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&facets[0][field]=country.name&facets[0][sort]=count:asc&limit=0

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "facets": [
        {
          "field": "country",
          "sort": "count:asc"
        }
      ],
      "limit": 0
    }
    
  • Alter the field that is sorted on. This lists the first 5 countries (alphabetically) and the number of reports for each. field, sort, limit

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&facets[0][field]=country.name&facets[0][sort]=value:asc&facets[0][limit]=5&limit=0

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "facets": [
        {
          "field": "country",
          "sort": "value:asc",
          "limit": 5
        }
      ],
      "limit": 0
    }
    
  • Use intervals to facet by dates. Note that facet limits don't apply for date fields - to restrict the number requires a facet filter - see the next example. This shows all years (ordered ascending) and the number of reports for each. field, interval

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&facets[0][field]=date.original&facets[0][interval]=year&limit=0

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "facets": [
        {
          "field": "date.original",
          "interval": "year"
        }
      ],
      "limit": 0
    }
    
  • Restrict the facetted results with a facet filter. This returns the five countries with most reports tagged with theme 'Coordination'. field, filter field, filter value, sort, limit

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&facets[0][field]=country&facets[0][filter][field]=theme&facets[0][filter][value]=Coordination&facets[0][sort]=count:desc&facets[0][limit]=5&limit=0

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "facets": [
        {
          "field": "country",
          "filter":
            {
              "field": "theme",
              "value": "Coordination"
            },
          "sort": "count:desc",
          "limit": 5
        }
      ],
      "limit": 0
    }
    
  • Get more than one facet in the same request. This shows the top 5 sources for reports filtered on France and Spain. name, field, filter field, filter value, sort, limit

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&facets[0][name]=French&facets[0][filter][field]=country&facets[0][filter][value]=France&facets[0][field]=source&facets[0][sort]=count:desc&facets[0][limit]=5&facets[1][name]=Spanish&facets[1][filter][field]=country&facets[1][filter][value]=Spain&facets[1][field]=source&facets[1][sort]=count:desc&facets[1][limit]=5&limit=0

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "facets": [
        {
          "name": "French",
          "field": "source",
          "filter":
            {
              "field": "country",
              "value": "France"
            },
          "sort": "count:desc",
          "limit": 5
        },
        {
          "name": "Spanish",
          "field": "source",
          "filter":
            {
              "field": "country",
              "value": "Spain"
            },
          "sort": "count:desc",
          "limit": 5
        }
      ],
      "limit": 0
    }
    

Limit

(integer) How many results to return. Must be between 0 and 1000, defaults to 10.

Example:

  • Get more than the default number of results. This returns all of the countries indexed (note the totalcount).

    GET:

    https://api.reliefweb.int/v1/countries?appname=apidoc&limit=300

    POST:

    https://api.reliefweb.int/v1/countries?appname=apidoc
    {
      "limit": 300
    }
    

Offset

(integer) How many results to skip. Used for paging through results or for getting more than the limit. Must be greater than 0, defaults to 0.

Example:

  • Start the results at a specified point. As there are more than 1000 sources, they can't be returned in one query. Assuming a previous query with a limit of 1000, this returns the next sources in sequence (and would normally also be used with the limit parameter).

    GET:

    https://api.reliefweb.int/v1/sources?appname=apidoc&offset=1000

    POST:

    https://api.reliefweb.int/v1/sources?appname=apidoc
    {
      "offset": 1000
    }
    

Sort

(array) Sortable field names and their direction desc or asc in the form field:order. The order of the field names in the array will determine the priority of the sorting.

Note: requests with a query will be sorted by relevance. If there is no sort specified, results may not be consistent.

For the most recent results, use the preset latest.

Example:

  • Sort by more than one field. This returns reports sorted by date first and then by title.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&sort[]=date:desc&sort[]=title:asc

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "sort": ["date:desc", "title:asc"]
    }
    

Profile

(string) A shorthand specification for which sets of fields to include in result.

Defaults to minimal. Fields returned are affected by the fields parameter.

Example:

  • Get limited fields without specifying all of them. This returns list profile fields for countries and adds the iso3 code.

    GET:

    https://api.reliefweb.int/v1/countries?appname=apidoc&profile=list&fields[include][]=iso3

    POST:

    https://api.reliefweb.int/v1/countries?appname=apidoc
    {
      "profile": "list",
      "fields":
        {
          "include": ["iso3"]
        }
    }
    

Preset

(string) A shorthand specification of sets of fields, filters and sort order for common use-cases. Similar to profile but with more opinions.

  • analysis: Include archived disasters and expired jobs and training which otherwise would be excluded from results. This is useful for visualizing trends and performing analysis of past content.
  • latest: Sorts by date for appropriate content types. Countries and sources sorted by id. Use this for list requests.
  • minimal: The default setting applies sensible status filters for most requests.

More information and the presets for each content type are specified in the preset settings section.

Example:

  • Query for 'French' with latest preset.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&preset=latest&query[value]=French&fields[include][]=language.name

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "preset": "latest",
      "query":
        {
          "value": "French"
        },
      "fields":
        {
          "include": ["language.name"]
        }
    }
    
  • Query for 'French' with minimal preset.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&preset=minimal&query[value]=French&fields[include][]=language.name

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "preset": "minimal",
      "query":
        {
          "value": "French"
        },
      "fields":
        {
          "include": ["language.name"]
        }
    }
    

Fields

(array) Arrays of fields to return in the result. To be used in conjunction with the profile parameter to personalize the fields returned and streamline requests.

Fields are made up of two parts: include and exclude.

  • include: (array): Fields to include.
  • exclude: (array): Fields to exclude.

In the examples for many of the other parameters, we have used fields[include] to show that we are getting the results we wanted. If you want to filter reports by a particular format, for example, it's often useful to include the format.name field while refining the query, to check you're getting what you expected, even if you remove it for the final results.

Examples:

  • The latest 3 reports with urls.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&limit=3&preset=latest&fields[include][]=url

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "limit": 3,
      "preset": "latest",
      "fields": {
          "include": ["url"]
      }
    }
    
  • The latest 3 reports with no fields.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&limit=3&preset=latest&fields[exclude][]=title

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "limit": 3,
      "preset": "latest",
      "fields": {
          "exclude": ["title"]
      }
    }
    
  • The latest 3 reports with list profile excluding source fields.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&limit=3&preset=latest&profile=list&fields[exclude][]=source

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "limit": 3,
      "preset": "latest",
      "profile": "list",
      "fields": {
          "exclude": ["source"]
      }
    }
    

Note: when using source in queries it defaults to source.name, when used with fields it expands to source.name, source.id, source.href, source.longname, source.shortname, source.homepage and source.type.

Verbose

(int) A helper for creating correct API calls, setting verbose=1 adds a details section to the response to display the query parameters as a JSON object.

This is for checking how the GET parameters are translated into JSON, or that the POST parameters sent are as intended.

To see how this works, try the following GET query - a complicated example from the facet documentation with the verbose parameter added - and compare it with the details section of the response:

https://api.reliefweb.int/v1/reports?appname=apidoc&verbose=1&facets[0][name]=French&facets[0][filter][field]=country&facets[0][filter][value]=France&facets[0][field]=country&facets[0][sort]=count:desc&facets[0][limit]=5&facets[1][name]=Spanish&facets[1][filter][field]=country&facets[1][filter][value]=Spain&facets[1][field]=country&facets[1][sort]=count:desc&facets[1][limit]=5&limit=0

Result fields

Structure of a result

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

  • href: Url of the current request.
  • time: Milliseconds taken to calculate the response.
  • links: HAL-type links to previous and next resources, for lists, or to collection for items.
  • totalCount: Total number of results that match the request.
  • count: Number of results returned in this result.
  • data: All the information:
    • 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 selected by fields and/or profile parameter (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?profile=full&limit=1

    Commented response schema:

    {
      "href": // url of request - Post request bodies aren't reflected here.
      "time": // milliseconds taken to calculate response.
      "links": // To be used for exploring further results.
        {
          "self": // current request.
          "next": // next page of results in list. Previous link also shown when appropriate.
        },
      "totalCount": // Total results in set.
      "count": // Number of results returned in this response.
      "data": // The requested results.
        [
          {
            "id": // ReliefWeb id.
            "score": // Relevance calculated for queries.
            "href": // API url for more on this resource.
            "fields": // Fields returned for this result - can be adjusted through the profile, preset and fields parameters.
          }
        ]
    }
    

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=apidoc&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=apidoc&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=apidoc&query[field]=country&query[value]=France

Examples, tips, suggestions

Please let us know what would be helpful in this section.

Limit for GET queries

GET queries can sometimes be longer than 2048 characters, but this will not work with all browsers and becomes difficult to read. For more complex queries, putting the query in a POST request is recommended.

Client libraries

There are very simple client libraries for PHP and Go. Please use them!

Getting exact results

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=apidoc&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=apidoc&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=apidoc
{
"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=apidoc&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=apidoc&filter[field]=disaster.name.exact&filter[value]=Myanmar: Earthquake - Apr 2016&fields[include][]=disaster.name

Using totalcount

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=apidoc&filter[field]=source.shortname&filter[value]=IFRC&limit=0

Convert POST requests to GET requests.

The sequence of parentheses in GET requests can get confusing quickly, but it's often quicker to fire the request through a browser. Creating a request as a set of keys and values, as you would for a POST request, can help while you're tweaking it, and then it can be converted.

For example, this 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=apidoc
{
"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=apidoc&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=apidoc&verbose=1&filter[operator]=AND&filter[conditions][0][field]=headline&filter[conditions][1][field]=country&filter[conditions][1][value][]=France

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.

There is a limit on the length of GET requests, and often it's easier to see what's what with a JSON object than a query string.

Advanced use of the query field.

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=apidoc&fields[include][]=source.name&query[fields][]=title^10&query[fields][]=source.name^1&query[value]=climate
    https://api.reliefweb.int/v1/reports?appname=apidoc&fields[include][]=source.name&query[fields][]=title^1&query[fields][]=source.name^10&query[value]=climate
  • Searching for an Exact Phrase

    Normal search querying breaks each individual word out into a search term and combines it via the operator to form a complete query. By using double quotes around phrases in the query, multiple words will be treated as one long string.

    Compare:

    https://api.reliefweb.int/v1/reports?appname=apidoc&query[fields][]=title&query[value]=hot weather
    https://api.reliefweb.int/v1/reports?appname=apidoc&query[fields][]=title&query[value]="hot weather"
  • Override the Operator

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

    Compare:

    https://api.reliefweb.int/v1/reports?appname=apidoc&sort[]=date:desc&query[fields][]=title&query[value]=hot AND cold&query[operator]=OR
    https://api.reliefweb.int/v1/reports?appname=apidoc&sort[]=date:desc&query[fields][]=title&query[value]=hot OR cold&query[operator]=OR
    https://api.reliefweb.int/v1/reports?appname=apidoc&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=apidoc&fields[include][]=source.name&query[value]=title:climate
    https://api.reliefweb.int/v1/reports?appname=apidoc&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=apidoc&query[value]=("situation report" AND humanitarian) OR country:France

Fields tables

Use tabs to see lists of fields by content type.The summary tab shows all fields with links to the content types they are used in. The other tabs show the names of fields with a short description, its type, and the abbreviations used in advanced searches on ReliefWeb.

For advanced use, the attributes column shows whether a field can be used for search - in a query or a filter - sorts and facets or with the "exact" qualifier. Multi means a returned field can have mulitple values (objects) like country or theme. common fields make it easier to search. For example, source.common contains both the full name and the short name of the source, so both "OCHA" and "Office for the Coordination of Humanitarian Affairs" will return the same result. ".common" fields often have an ".exact" version too.

Note: In the field descriptions in this table, fields that have subfields are often described as defaulting to one of those subfields. This refers to a search, and not the result. So, for example, a query[fields][]=country is equivalent to query[fields][]=country.name. The result will return JSON objects for each country, not only the names.

NameTypeAbbreviationContent Types
bodystringreports, jobs, training
body-htmlstringreports, jobs, training
career_categoriesarrayjobs, training
career_categories
.id
integerCCjobs, training
career_categories
.name
stringjobs, training
cityarrayjobs, training
city.namestringjobs, training
content_typearraysources
countryarrayreports, jobs, training, disasters, sources
country.idintegerCreports, jobs, training, disasters, sources
country.iso3stringreports, jobs, training, disasters, sources
country.namestringreports, jobs, training, disasters, sources
country.primarybooleanreports, jobs, training, disasters, sources
country.shortnamestringreports, jobs, training, disasters, sources
coststringtraining
currentbooleancountries, disasters
dateobjectreports, jobs, disasters
date.changeddatereports, jobs, training
date.closingdateDCjobs
date.createddateDAreports, jobs, training, disasters
date.enddateDEtraining
date.originaldateDOreports
date.registrationdateDRtraining
date.startdateDStraining
descriptionstringcountries, disasters, sources
description-htmlstringcountries, disasters, sources
disasterarrayreports
disaster.idintegerDreports
disaster.namestringreports
disaster.glidestringreports
disaster.typearrayreports
disaster.type.codestringreports
disaster.type.idintegerreports
disaster.type.namestringreports
disaster.type.primarybooleanreports
disaster_typestringreports
disaster_type.codearrayreports
disaster_type.idintegerDTreports
disaster_type.namestringreports
disclaimerstringsources
experiencearrayjobs
experience.idintegerEjobs
experience.namestringjobs
featurearrayreports
feature.idintegerreports
feature.namestringreports
featuredbooleancountries, disasters
filearrayreports, jobs, training
file.copyrightstringreports
file.descriptionstringreports, jobs, training
file.filenamestringreports, jobs, training
file.idintegerreports, jobs, training
file.mimetypestringreports, jobs, training
file.previewarrayreports
file.preview
.url
stringreports
file.preview
.url-large
stringreports
file.preview
.url-small
stringreports
file.preview
.url-thumb
stringreports
file.urlstringreports, jobs, training
formatarrayreports, training
format.idintegerFreports, training
format.namestringreports, training
fts_idintegersources
glidestringdisasters
headlinearrayreports
headline.featuredstringreports
headline.imagearrayreports
headline.image
.caption
stringreports
headline.image
.copyright
stringreports
headline.image
.filename
stringreports
headline.image
.id
integerreports
headline.image
.mimetype
stringreports
headline.image
.url
stringreports
headline.summarystringreports
headline.titlestringreports
homepagestringsources
how_to_applystringjobs
how_to_apply-htmlstringjobs
how_to_registerstringtraining
how_to_register-htmlstringtraining
idintegerreports, jobs, training, countries, disasters, sources
imagearrayreports
image.captionstringreports
image.copyrightstringreports
image.filenamestringreports
image.idintegerreports
image.mimetypestringreports
image.urlstringreports
image.url-largestringreports
image.url-smallstringreports
image.url-thumbstringreports
iso3stringcountries
languagearrayreports, jobs, training
language.codestringreports, jobs, training
language.idintegerLreports, jobs, training
language.namestringreports, jobs, training
longnamestringsources
namestringcountries, disasters, sources
ocha_productarrayreports
ocha_product.idintegerreports
ocha_product.namestringreports
originstringreports
primary_countryarrayreports, disasters
primary_country
.id
integerPCreports, disasters
primary_country
.iso3
stringreports, disasters
primary_country
.name
stringreports, disasters
primary_country
.shortname
stringreports, disasters
primary_typearraydisasters
primary_type.idintegerTYdisasters
primary_type.namestringdisasters
profilestringcountries, disasters
profile.overviewstringcountries, disasters
profile.overview-htmlstringcountries, disasters
profile.key_contentarraycountries, disasters
profile.key_content.titlestringcountries, disasters
profile.key_content.activearraycountries, disasters
profile.key_content.active.urlstringcountries, disasters
profile.key_content.active.titlestringcountries, disasters
profile.key_content.active.imagestringcountries, disasters
profile.key_content.archivearraycountries, disasters
profile.key_content.archive.urlstringcountries, disasters
profile.key_content.archive.titlestringcountries, disasters
profile.key_content.archive.imagestringcountries, disasters
profile.appeals_response_plansarraycountries, disasters
profile.appeals_response_plans.titlestringcountries, disasters
profile.appeals_response_plans.activearraycountries, disasters
profile.appeals_response_plans.active.urlstringcountries, disasters
profile.appeals_response_plans.active.titlestringcountries, disasters
profile.appeals_response_plans.active.imagestringcountries, disasters
profile.appeals_response_plans.archivearraycountries, disasters
profile.appeals_response_plans.archive.urlstringcountries, disasters
profile.appeals_response_plans.archive.titlestringcountries, disasters
profile.appeals_response_plans.archive.imagestringcountries, disasters
profile.useful_linksarraycountries, disasters
profile.useful_links.titlestringcountries, disasters
profile.useful_links.activearraycountries, disasters
profile.useful_links.active.urlstringcountries, disasters
profile.useful_links.active.titlestringcountries, disasters
profile.useful_links.active.imagestringcountries, disasters
related_glidearraydisasters
shortnamestringcountries, sources
sourcearrayreports, jobs, training
source.disclaimerstringsources
source.homepagestringreports, jobs, training
source.idintegerSreports, jobs, training
source.longnamestringreports, jobs, training
source.namestringreports, jobs, training
source.shortnamestringreports, jobs, training
source.spanish_namestringreports, jobs, training
source.typearrayreports, jobs, training
source.type.idintegerSTreports, jobs, training
source.type.namestringreports, jobs, training
spanish_namestringsources
statusstringreports, jobs, training, countries, sources
themearrayreports, jobs, training
theme.idintegerTreports, jobs, training
theme.namestringreports, jobs, training
titlestringreports, jobs, training
training_languagestringtraining
training_language.idintegerTLtraining
training_language.namestringtraining
training_language.codestringtraining
typearrayjobs, training, disasters, sources
type.codestringdisasters
type.idintegerTYjobs, training, disasters, sources
type.namestringjobs, training, disasters, sources
type.primarybooleandisasters
urlstringreports, jobs, training, countries, disasters, sources
urlstringreports, jobs, training, countries, disasters, sources
vulnerable_groupsarrayreports
vulnerable_groups
.id
integerVGreports
vulnerable_groups
.name
stringreports
NameDescriptionTypeAttributesAbbreviation
bodyMain text in Markdown formatstringsearchable
body-htmlMain text in HTML formatstring
countryShortcut for country - defaults to country.namestringsearchable facetable exact multi common
country.idId for country used by ReliefWebintegersearchable facetable exactC
country.iso3ISO 3166-1 alpha-3 codestringsearchable facetable exact
country.nameName of country in Englishstringsearchable facetable exact
country.primaryFlag to indicate this is the primary countryboolean
country.shortnameShort name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsearchable facetable exact
dateShortcut for date fields - defaults to date.createdobject
date.changedDate entry modified on ReliefWeb (ISO 8601)datesortable facetable
date.createdDate entry created on ReliefWeb (ISO 8601)datesortable facetableDA
date.originalDate entry first published by original source (ISO 8601)datesortable facetableDO
disasterShortcut for related disaster - defaults to disaster.namestringsearchable facetable exact multi common
disaster.idId for related disaster used by ReliefWebintegersearchable facetableD
disaster.nameName assigned to the disaster based on the ReliefWeb disaster naming conventionstringsearchable facetable exact
disaster.glideGlobal IDEntifier number (GLIDE) of the disasterstringsearchable facetable
disaster.typeDisaster type of the associated disaster. Note this may be different to the `disaster_type` of a report. Defaults to disaster.type.namestringsearchable facetable exact multi common
disaster.type.codeCode for the disaster type of the associated disaster.stringsearchable facetable
disaster.type.idId for the disaster type of the associated disaster.integersearchable facetable
disaster.type.nameLink for valuesstringsearchable facetable exact
disaster.type.primaryWhether this is the primary disaster type for the associated disaster.boolean
disaster_typeShortcut for disaster type - defaults to disaster_type.namestringsearchable facetable exact multi common
disaster_type.idId for disaster type used by ReliefWebintegersearchable facetableDT
disaster_type.nameLink for valuesstringsearchable facetable exact
disaster_type.codeGLIDE hazard code for disaster type.stringsearchable facetable
featuredefaults to feature.namestringsearchable facetable exact multi common
feature.idId for feature used by ReliefWebintegersearchable facetable
feature.nameLink for values.stringsearchable facetable exact
fileFile attachment shortcut - defaults to file.idarraymulti
file.copyrightCopyright of file attachmentstringsearchable
file.descriptionDescription of file attachmentstringsearchable
file.filenameFile name of file attachmentstring
file.idId of file attachment used by ReliefWebintegersearchable
file.mimetypeMIME type of file attachmentstring
file.previewShortcut for preview image of file attachment - defaults to file.preview.urlarraymulti
file.preview
.url
Link to preview image of file attachmentstring
file.preview
.url-large
Link to a large preview image with a width of 680pxstring
file.preview
.url-small
Link to a small preview image with a width of 200pxstring
file.preview
.url-thumb
Link to a thumbnail preview image with a maximum width of 220px and a maximum height of 100pxstring
file.urlLink to file attachmentstring
formatShortcut for content format - defaults to format.namestringsearchable facetable exact multi common
format.idId of content format used by ReliefWebintegersearchable facetableF
format.nameLink for valuesstringsearchable facetable exact
headlineShortcut for headline - defaults to headline.titlearray
headline.featuredstringsortable searchable facetable
headline.imageShortcut for headline image - defaults to headline.image.idarray
headline.image
.id
Unique id of headline image used by ReliefWebintegersearchable
headline.image
.mimetype
MIME type of the headline imagestring
headline.image
.filename
File name of the headline imagestring
headline.image
.caption
Caption attached to the headline imagestringsearchable
headline.image
.copyright
Copyright attached to the headline imagestringsearchable
headline.image
.url
URL of the headline imagestring
headline.summarySummary of body, if report is selected as headline. Typically 180-190 characters longstringsearchable
headline.titleHeadline text, if report is selected as headline. Typically 100-120 characters longstringsortable searchable
idUnique id of report used by ReliefWebintegersortable searchable
imageImage shortcut - defaults to image.idinteger
image.captionCaption attached to the imagestringsearchable
image.copyrightCopyright attached to the imagestringsearchable
image.idUnique id of image used by ReliefWebintegersearchable
image.mimetypeMIME type of the imagestring
image.filenameFile name of the imagestring
image.urlLink to the original imagestring
image.url-largeLink to a large image with a width of 680pxstring
image.url-smallLink to a small image with a width of 200pxstring
image.url-thumbLink to a thumbnail image with a maximum width of 220px and a maximum height of 100pxstring
languageShortcut for language - defaults to language.namestringsearchable facetable exact multi common
language.codeISO 639-1 code of the language the entry is written instringsearchable facetable
language.idId for language of report used by ReliefWebintegerfacetableL
language.nameLanguage the report is written in - Link for values.stringsearchable facetable exact
ocha_productShortcut for OCHA product - defaults to ocha_product.namestringsearchable facetable exact multi common
ocha_product.idId of OCHA product used by ReliefWebintegersearchable facetable
ocha_product.nameLink for valuesstringsearchable facetable exact
originUrl of original report when it was added to ReliefWebstring
primary_countryShortcut for primary country - defaults to primary_country.namestringsearchable facetable exact multi common
primary_country
.id
Id of primary country used by ReliefWebintegersortable searchable facetablePC
primary_country
.name
Link for more informationstringsortable searchable facetable exact
primary_country
.shortname
Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsortable searchable facetable exact
primary_country
.iso3
ISO 3166-1 alpha-3 codestringsortable searchable facetable exact
sourceShortcut for sources - defaults to source.namestringsearchable facetable exact multi common
source.disclaimerDisclaimer information for the sourcestringsearchable
source.idId for source used by ReliefWebintegersearchable facetableS
source.nameCommon name of sourcestringsearchable facetable exact
source.longnameOfficial name of the source if different from source.namestringsearchable facetable exact
source.homepageURL of the source's primary websitestringsearchable
source.shortnameShort name of the source, typically an acronym e.g. UNICEFstringsearchable facetable exact
source.spanish_nameSpanish name of the sourcestringsearchable facetable exact
source.typeShortcut for source type - defaults to source.type.namearray
source.type.idId for source type used by ReliefWebintegersearchable facetableST
source.type.nameLink for valuesstringsearchable facetable exact
statusstringsearchable facetable
themeShortcut for theme - defaults to theme.namestringsearchable facetable exact multi common
theme.idId of theme used by ReliefWebintegersearchable facetableT
theme.nameLink for valuesstringsearchable facetable exact
titleTitle of reportstringsortable searchable exact
urlCanonical urlstring
url_aliasFriendly' url of the reportstringsearchable
vulnerable_groupsShortcut for vulnerable groups - defaults to vulnerable_groups.namestringsearchable facetable exact multi common
vulnerable_groups
.id
Id for vulnerable groups used by ReliefWebintegersearchable facetableVG
vulnerable_groups
.name
Link for valuesstringsearchable facetable exact
NameDescriptionTypeAttributesAbbreviation
countryShortcut for country - defaults to country.namestringsearchable facetable exact multi common
country.idId for country used by ReliefWebintegersearchable facetableC
country.iso3ISO 3166-1 alpha-3 codestringsearchable facetable exact
country.primaryFlag to indicate this is the primary countryboolean
country.nameName of country in Englishstringsearchable facetable exact
country.shortnameShort name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsearchable facetable exact
currentDeprecatedbooleansortable facetable
dateShortcut for date - defaults to date.createdobjectsearchable facetable
date.createdDate when the disaster occurred (ISO 8601)datesortable facetableDA
descriptionDescription of the disaster in Markdown formatstringsearchable
description-htmlDescription of the disaster in HTML formatstring
featuredFlag to indicate if the disaster is featured on ReliefWeb home pagebooleansortable facetable
glideGlobal IDEntifier number (GLIDE) of the disasterstringsortable searchable exact
idUnique id of disaster used by ReliefWebintegersortable searchable
namestringsortable searchable exact
primary_countryShortcut for primary country - defaults to primary_country.namestringsearchable facetable exact multi common
primary_country
.id
Id of primary country used by ReliefWebintegersortable searchable facetable
primary_country
.iso3
ISO 3166-1 alpha-3 codestringsortable searchable facetable exact
primary_country
.name
Link for more informationstringsortable searchable facetable exact
primary_country
.shortname
Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsortable searchable facetable exact
primary_typeShortcut for primary disaster type - defaults to primary_type.namestringsearchable facetable exact multi common
primary_type.idId for primary disaster type used by ReliefWebintegersearchable facetable
primary_type.nameName of primary disaster typestringsearchable facetable exact
profiledefaults to profile.overviewstringsearchable
profile.overviewProfile of the country in Markdown formatstringsearchable
profile.overview-htmlProfile of the country in HTML formatstring
profile.key_contentLatest situation reports and analysisarray
profile.key_content.title"Key Content"string
profile.key_content.activeArray of links for current key content for the countryarray
profile.key_content.active.urlCurrent key content link urlstring
profile.key_content.active.titleCurrent key content link titlestring
profile.key_content.active.imageCurrent key content link imagestring
profile.key_content.archiveArray of links for archive key content for the countryarray
profile.key_content.archive.urlArchive key content link urlstring
profile.key_content.archive.titleArchive key content link titlestring
profile.key_content.archive.imageArchive key content link imagestring
profile.appeals_response_plansAppeals and Response Plans for this countryarray
profile.appeals_response_plans.title"Appeals & Response Plans"string
profile.appeals_response_plans.activeArray of links for current appeals and plansarray
profile.appeals_response_plans.active.urlCurrent appeal or plan urlstring
profile.appeals_response_plans.active.titleCurrent appeal or plan titlestring
profile.appeals_response_plans.active.imageCurrent appeal or plan imagestring
profile.appeals_response_plans.archiveArray of links for archive appeals and plansarray
profile.appeals_response_plans.archive.urlArchive appeal or plan urlstring
profile.appeals_response_plans.archive.titleArchive appeal or plan titlestring
profile.appeals_response_plans.archive.imageArchive appeal or plan imagestring
profile.useful_linksUseful links to external sitesarray
profile.useful_links.title"Useful links"string
profile.useful_links.activeArray of useful linksarray
profile.useful_links.active.urlUseful link urlstring
profile.useful_links.active.titleUseful link titlestring
profile.useful_links.active.imageUseful link imagestring
related_glideRelated Global IDEntifier number (GLIDE)arraysearchable exact
statuscurrent', 'alert', 'past'stringsearchable facetable
typeShortcut for disaster type - defaults to type.namestringsearchable facetable exact multi common
type.codeCode of disaster typestringsortable searchable facetable
type.idId of disaster type used by ReliefWebintegersearchable facetableDT
type.nameLink for valuesstringsearchable facetable exact
type.primaryWhether disaster type is primary or notboolean
urlCanonical urlstring
url_aliasFriendly' url of the disasterstringsearchable
NameDescriptionTypeAttributesAbbreviation
currentDeprecatedbooleansortable facetable
descriptionDescription of the country in Markdown formatstringsearchable
description-htmlDescription of the country in HTML formatstring
featuredFlag to indicate if the country is featured on ReliefWeb home pagebooleansortable facetable
idUnique id of country used by ReliefWebintegersortable searchable
iso3ISO 3166-1 alpha-3 codestringsortable searchable exact
nameCountry name in Englishstringsortable searchable exact
profiledefaults to profile.overviewstringsearchable
profile.overviewProfile of the country in Markdown formatstringsearchable
profile.overview-htmlProfile of the country in HTML formatstring
profile.key_contentLatest situation reports and analysisarray
profile.key_content.title"Key Content"string
profile.key_content.activeArray of links for current key content for the countryarraymulti
profile.key_content.active.urlCurrent key content link urlstring
profile.key_content.active.titleCurrent key content link titlestring
profile.key_content.active.imageCurrent key content link imagestring
profile.key_content.archiveArray of links for archive key content for the countryarraymulti
profile.key_content.archive.urlArchive key content link urlstring
profile.key_content.archive.titleArchive key content link titlestring
profile.key_content.archive.imageArchive key content link imagestring
profile.appeals_response_plansAppeals and Response Plans for this countryarray
profile.appeals_response_plans.title"Appeals & Response Plans"string
profile.appeals_response_plans.activeArray of links for current appeals and plansarraymulti
profile.appeals_response_plans.active.urlCurrent appeal or plan urlstring
profile.appeals_response_plans.active.titleCurrent appeal or plan titlestring
profile.appeals_response_plans.active.imageCurrent appeal or plan imagestring
profile.appeals_response_plans.archiveArray of links for archive appeals and plansarraymulti
profile.appeals_response_plans.archive.urlArchive appeal or plan urlstring
profile.appeals_response_plans.archive.titleArchive appeal or plan titlestring
profile.appeals_response_plans.archive.imageArchive appeal or plan imagestring
profile.useful_linksUseful links to external sitesarray
profile.useful_links.title"Useful links"string
profile.useful_links.activeArray of useful linksarraymulti
profile.useful_links.active.urlUseful link urlstring
profile.useful_links.active.titleUseful link titlestring
profile.useful_links.active.imageUseful link imagestring
shortnameShort name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsortable searchable exact
statusWhether country has an active situationstringsearchable facetable
urlCanonical urlstring
url_aliasFriendly' url of the countrystringsearchable
NameDescriptionTypeAttributesAbbreviation
bodyDescription of job in Markdown formatstringsearchable
body-htmlDescription of job in HTML formatstring
career_categoriesShortcut for career categories - defaults to career_categories.namestringsearchable facetable exact multi common
career_categories
.id
Id for career categories used by ReliefWebintegersearchable facetableCC
career_categories
.name
Link for valuesstringsearchable facetable exact
cityShortcut for city - defaults to city.namestringsearchable facetable exact multi common
city.nameName of city in Englishstringsearchable facetable exact
countryShortcut for country - defaults to country.namestringsearchable facetable exact multi common
country.idId for country used by ReliefWebintegersearchable facetableC
country.primaryFlag to indicate this is the primary countryboolean
country.nameName of country in Englishstringsearchable facetable exact
country.shortnameShort name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsearchable facetable exact
country.iso3ISO 3166-1 alpha-3 codestringsearchable facetable exact
dateShortcut for date - defaults to date.createdobject
date.changedDate entry modified on ReliefWeb (ISO 8601)datesortable facetable
date.closingDate job closes to applicants (ISO 8601)datesortable facetableDC
date.createdDate entry created on ReliefWeb (ISO 8601)datesortable facetableDA
experienceShortcut for experience requirement - defaults to experience.namestringsearchable facetable exact multi common
experience.idId for experience requirement used by ReliefWebintegersearchable facetableE
experience.nameLink for values.stringsearchable facetable exact
fileShortcut for file attachment - defaults to file.idarraymulti
file.descriptionDescription of the file attachmentstringsearchable
file.filenameFile name of the attachmentstring
file.idId for file attachment used by ReliefWebintegersearchable
file.mimetypeMIME type of the file attachmentstring
file.urlURL of the file attachmentstring
how_to_applyApplication instructions for the job in Markdown formatstringsearchable
how_to_apply-htmlApplication instructions for the job in HTML formatstring
idUnique id of job used by ReliefWebintegersortable searchable
languageLanguage of job postingstringsearchable facetable exact multi common
language.idId for language used by ReliefWebintegersortable facetable
language.nameName of languagestringsortable facetable exact
language.codeCode for languagestringsortable facetable exact
sourceShortcut for source - defaults to source.namestringsearchable facetable exact multi common
source.homepageURL of the source's primary websitestringsearchable
source.idId for source used by ReliefWebintegersearchable facetable exactS
source.longnameOfficial name of the source if different from source.namestringsearchable facetable exact
source.nameCommon name of sourcestringsearchable facetable exact
source.shortnameShort name of the source, typically an acronym e.g. UNICEFstringsearchable facetable exact
source.spanish_nameSpanish name of the sourcestringsearchable facetable exact
source.typeShortcut for source type - defaults to source.type.namearray
source.type.idId for source type used by ReliefWebintegersearchable facetableST
source.type.nameLink for valuesstringsearchable facetable exact
statusWhether job is still currentstringsearchable facetable
themeShortcut for theme - defaults to theme.namestringsearchable facetable exact multi common
theme.idId for theme used by ReliefWebintegersearchable facetableT
theme.nameLink for valuesstringsearchable facetable exact
titleJob titlestringsortable searchable exact
typeShortcut for type - defaults to type.namestringsearchable facetable exact multi common
type.idId for job type used by ReliefWebintegersearchable facetableTY
type.nameLink for valuesstringsearchable facetable exact
urlCanonical urlstring
url_aliasFriendly' url of the jobstringsearchable
NameDescriptionTypeAttributesAbbreviation
bodyTraining description in Markdown formatstringsearchable
body-htmlTraining description in HTML formatstring
career_categoriesShortcut for career categories - defaults to career_categories.namestringsearchable facetable exact multi common
career_categories
.id
Id for career categories used by ReliefWebintegersearchable facetableCC
career_categories
.name
Link for valuesstringsearchable facetable exact
cityShortcut for city - defaults to city.namestringsearchable facetable exact multi common
city.nameName of city in Englishstringsearchable facetable exact
costfree or fee-basedstringsearchable facetable
countryShortcut for country - defaults to country.namestringsearchable facetable exact multi common
country.idId for country used by ReliefWebintegersearchable facetableC
country.iso3ISO 3166-1 alpha-3 codestringsearchable facetable exact
country.nameName of country in Englishstringsearchable facetable exact
country.primaryFlag to indicate this is the primary countryboolean
country.shortnameShort name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsearchable facetable exact
dateShortcut for date - defaults to date.createdobject
date.changedDate when the entry was last modified on ReliefWeb (ISO 8601)datesortable facetable
date.createdDate when the entry was created on ReliefWeb (ISO 8601)datesortable facetableDA
date.endDate training ends (ISO 8601)datesortable facetableDE
date.registrationDate registration closes (ISO 8601)datesortable facetableDR
date.startDate training starts (ISO 8601)datesortable facetableDS
fileShortcut for file attachment - defaults to file.idarraymulti
file.descriptionDescription of the file attachmentstringsearchable
file.filenameFile name of the attachmentstring
file.idId for file attachment used by ReliefWebintegersearchable
file.mimetypeMIME type of the file attachmentstring
file.urlURL of the file attachmentstring
formatShortcut for training format - defaults to format.namestringsearchable facetable exact multi common
format.idId for training format used by ReliefWebintegersearchable facetableF
format.nameLink to valuesstringsearchable facetable exact
how_to_registerRegistration information in Markdown formatstringsearchable
how_to_register
-html
Registration information in HTML formatstring
idUnique id for training opportunity used by ReliefWebintegersortable searchable
languageShortcut for language - defaults to language.namestringsearchable facetable exact multi common
language.codeISO 639-1 code of the language the entry is written instringsearchable facetable exact
language.idId for language used by ReliefWebintegerfacetableL
language.nameLanguage in which post is written (not necessarily language in which the training will be held). Link for values.stringsearchable facetable exact
sourceShortcut for source - defaults to source.namestringsearchable facetable exact multi common
source.idId for source used by ReliefWebintegersearchable facetableS
source.nameCommon name of sourcestringsearchable facetable exact
source.longnameOfficial name of the source if different from source.namestringsearchable facetable exact
source.homepageURL of the source's primary websitestringsearchable
source.shortnameShort name of the source, typically an acronym e.g. UNICEFstringsearchable facetable exact
source.spanish_nameSpanish name of the sourcestringsearchable facetable exact
source.typeShortcut for source type - defaults to source.type.namearray
source.type.idId for source type used by ReliefWebintegersearchable facetableST
source.type.nameLink for valuesstringsearchable facetable exact
statusWhether training is still currentstringsearchable facetable
themeShortcut for theme - defaults to theme.namestringsearchable facetable exact multi common
theme.idId for theme used by ReliefWebintegersearchable facetableT
theme.nameLink for valuesstringsearchable facetable exact
titleTitle of coursestringsortable searchable exact
training_languageLanguage training is held in, defaults to training_language.namestringsearchable facetable exact multi common
training_language.idId of language training is held inintegerfacetableTL
training_language.nameName of language training is held in. Link for values.stringfacetable exact
training_language.codeCode of language training is held instringfacetable exact
typeShortcut for type - defaults to type.namestringsearchable facetable exact multi common
type.idId for training type used by ReliefWebintegersearchable facetableTY
type.nameLink for valuesstringsearchable facetable exact
urlCanonical urlstring
url_aliasFriendly' url of the trainingstringsearchable
NameDescriptionTypeAttributesAbbreviation
content_typeContent types published from this sourcearraysortable searchable
countryShortcut for country - defaults to country.namestringsearchable facetable exact multi common
country.idId for country used by ReliefWebintegersearchable facetableC
country.iso3ISO 3166-1 alpha-3 codestringsearchable facetable exact
country.nameName of the country in English where the source headquarters is locatedstringsearchable facetable exact
country.primaryFlag to indicate this is the primary countryboolean
country.shortnameShort name of the country in English where the source headquarters is locatedstringsearchable facetable exact
descriptionDescription of the source in Markdown formatstringsearchable
description-htmlDescription of the source in HTML formatstring
disclaimerDisclaimer informationstringsearchable
fts_idId number for organization used by FTSnumbersortable searchable
homepageURL of organizationstringsearchable
idUnique id for source used by ReliefWebintegersortable searchable
logoShortcut for logo - defaults to logo.urlobject
logo.filenameFile name of the logostring
logo.filesizeFile size of the logostring
logo.heightHeight of the logointeger
logo.idId for logo used by ReliefWebinteger
logo.mimetypeMIME type of the logostring
logo.urlURL of the logostring
logo.widthWidth of the logointeger
longnameOfficial name of source, where applicablestringsortable searchable exact
nameName of sourcestringsortable searchable exact
shortnameName of the source in abbreviated format, where applicablestringsortable searchable exact
spanish_nameName of the source in Spanishstringsortable searchable exact
statusWhether source is active or notstringsearchable facetable
typeShortcut for type of organization - defaults to type.namestringsearchable facetable exact multi common
type.idId of organization type used by ReliefWebintegersearchable facetableTY
type.nameLink for valuesstringsearchable facetable exact
urlCanonical urlstring
url_aliasFriendly' url of the sourcestringsearchable

Preset settings

Presets settings default to minimal.

Note: Each query parameter overrides any preset configuration apart from filter, which is joined with AND to any preset conditions and query where each setting is independently overridden.

For example, you can not get expired jobs using preset=latest, because the filter for this would be:

"filter": {
  "operator": "AND",
  "conditions": [
    {
      "field": "status",
      "value": ["published"],
      "operator": "OR"
    },
    {
      "field": "status",
      "value": ["expired"],
    }
  ]
}

and no job can have both statuses at the same time.

  • Analysis

    Countries - analysis

    {
      "query": {
        "fields": [
          "name",
          "shortname",
          "iso3",
          "status"
        ],
        "operator": "OR"
      },
      "filter": {}
    }
    

    Disasters - analysis

    {
      "query": {
        "fields": [
          "name",
          "glide",
          "description",
          "type",
          "country",
          "status"
        ],
        "operator": "OR"
      },
      "filter": {
        "field": "status",
        "value": ["alert", "alert-archive", "archive", "current", "past"],
        "operator": "OR"
      }
    }
    

    Jobs - analysis

    {
      "query": {
        "fields": [
          "title",
          "body",
          "career_categories",
          "country",
          "how_to_apply",
          "source",
          "status",
          "theme"
        ],
        "operator": "OR"
      },
      "filter": {
        "field": "status",
        "value": ["published", "expired"],
        "operator": "OR"
      }
    }
    

    Reports - analysis

    {
      "query": {
        "fields": [
          "body",
          "country",
          "disaster",
          "disaster_type",
          "format.name",
          "headline.title",
          "headline.summary",
          "language",
          "primary_country",
          "source",
          "status",
          "theme.name",
          "title",
          "vulnerable_groups"
        ],
        "operator": "OR"
      },
      "filter": {
        "field": "status",
        "value": ["published", "to-review"],
        "operator": "OR"
      }
    }
    

    Sources - analysis

    {
      "query": {
        "fields": [
          "title"
        ]
      },
      "filter": {
        "field": "status",
        "value": ["published"],
        "operator": "OR"
      }
    }
    

    Training - analysis

    {
      "query": {
        "fields": [
          "body",
          "country",
          "format",
          "source",
          "status",
          "theme",
          "title",
          "type"
        ],
        "operator": "OR"
      },
      "filter": {
        "field": "status",
        "value": ["published", "expired"],
        "operator": "OR"
      }
    }
    
  • Latest

    Countries - latest

    {
      "query": {
        "fields": [
          "name",
          "shortname",
          "iso3"
        ],
        "operator": "OR"
      },
      "sort": [
        "id:desc"
      ],
      "filter": {}
    }
    

    Disasters - latest

    {
      "query": {
        "fields": [
          "name",
          "status",
          "glide",
          "description",
          "type",
          "country"
        ],
        "operator": "OR"
      },
      "sort": [
        "date.created:desc"
      ],
      "filter": {
        "field": "status",
        "value": ["alert", "current", "past"],
        "operator": "OR"
      }
    }
    

    Jobs - latest

    {
      "query": {
        "fields": [
          "title",
          "body",
          "career_categories",
          "country",
          "how_to_apply",
          "source",
          "theme"
        ],
        "operator": "OR"
      },
      "sort": [
        "date.created:desc"
      ],
      "filter": {
        "field": "status",
        "value": ["published"],
        "operator": "OR"
      }
    }
    

    Reports - latest

    {
      "query": {
        "fields": [
          "body",
          "country",
          "disaster",
          "disaster_type",
          "format.name",
          "headline.title",
          "headline.summary",
          "language",
          "primary_country",
          "source",
          "theme.name",
          "title",
          "vulnerable_groups"
        ],
        "operator": "OR"
      },
      "sort": [
        "date.created:desc"
      ],
      "filter": {
        "field": "status",
        "value": ["published", "to-review"],
        "operator": "OR"
      }
    }
    

    Sources - latest

    {
      "query": {
        "fields": [
          "name",
          "shortname",
          "longname",
          "spanish_name"
        ],
        "operator": "OR"
      },
      "sort": [
        "id:desc"
      ],
      "filter": {
        "field": "status",
        "value": ["active", "inactive"],
        "operator": "OR"
      }
    }
    

    Training - latest

    {
      "query": {
        "fields": [
          "body",
          "country",
          "format",
          "source",
          "theme",
          "title",
          "type",
          "how_to_register",
          "career_categories",
          "training_language"
        ],
        "operator": "OR"
      },
      "sort": [
        "date.created:desc"
      ],
      "filter": {
        "field": "status",
        "value": ["published"],
        "operator": "OR"
      }
    }
    
  • Minimal

    Countries - minimal

    {
      "query": {
        "fields": [
          "name"
        ]
      },
      "filter": {}
    }
    

    Disasters - minimal

    {
      "query": {
        "fields": [
          "name"
        ]
      },
      "filter": {
        "field": "status",
        "value": ["alert", "current", "past"],
        "operator": "OR"
      }
    }
    

    Jobs - minimal

    {
      "query": {
        "fields": [
          "title"
        ]
      },
      "filter": {
        "field": "status",
        "value": ["published"],
        "operator": "OR"
      }
    }
    

    Reports - minimal

    {
      "query": {
        "fields": [
          "title"
        ]
      },
      "filter": {
        "field": "status",
        "value": ["published", "to-review"],
        "operator": "OR"
      }
    }
    

    Sources - minimal

    {
      "query": {
        "fields": [
          "name"
        ]
      },
      "filter": {
        "field": "status",
        "value": ["active", "inactive"],
        "operator": "OR"
      }
    }
    

    Training - minimal

    {
      "query": {
        "fields": [
          "title"
        ]
      },
      "filter": {
        "field": "status",
        "value": ["published"],
        "operator": "OR"
      }
    }