Index

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 FAQ 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 FAQ 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
    }
    
  • Use facet scopes. Adapting the previous example and adding a filter and a query (that, combined, have no results), the default scope (which is added for the sake of clarity; it doesn't need to be specified) gets sources for reports that match both the query and the filter (i.e. none). The query scope ignores the filter, but not the query, while the global scope ignores both the filter and the query. To illustrate the behavior, try the following query without the query and/or the filter. name, field, filter field, filter value, sort, limit, scope

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&query[value]=earthquake&filter[field]=country&filter[value]=Belgium&facets[0][name]=French-global&facets[0][filter][field]=country&facets[0][filter][value]=France&facets[0][field]=source&facets[0][sort]=count:desc&facets[0][limit]=5&facets[0][scope]=global&facets[1][name]=French-query&facets[1][filter][field]=country&facets[1][filter][value]=France&facets[1][field]=source&facets[1][sort]=count:desc&facets[1][limit]=5&facets[1][scope]=query&facets[2][name]=French-default&facets[2][filter][field]=country&facets[2][filter][value]=France&facets[2][field]=source&facets[2][sort]=count:desc&facets[2][limit]=5&facets[2][scope]=default&limit=0

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "earthquake"
        },
      "filter":
        {
          "field": "country",
          "value": "Belgium"
        },
      "facets": [
        {
          "name": "French-global",
          "field": "source",
          "filter":
            {
              "field": "country",
              "value": "France"
            },
          "sort": "count:desc",
          "limit": 5,
          "scope": "global"
        },
        {
          "name": "French-query",
          "field": "source",
          "filter":
            {
              "field": "country",
              "value": "France"
            },
          "sort": "count:desc",
          "limit": 5,
          "scope": "query"
        },
        {
          "name": "French-default",
          "field": "source",
          "filter":
            {
              "field": "country",
              "value": "France"
            },
          "sort": "count:desc",
          "limit": 5,
          "scope": "default"
        }
      ],
      "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 on the preset settings page.

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.

Slim

(int) A switch to remove the hypermedia links from the result.

The API was built while the debate about Hypermedia was near its peak, and duly implemented hypermedia links so that clients (human or machine) can navigate through the API like one navigates through a webpage.

To avoid the hypermedia links, reducing the size of the response a little, use the slim parameter.

Example:

  • Try this with and without the slim parameter.

    GET:

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

    POST:

    https://api.reliefweb.int/v1/countries?appname=apidoc
    {
      "slim": 1,
      "limit": 2
    }
    

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:

Example:

  • 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