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.

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!

To view the results of GET requests in a browser more clearly, consider using an extension:

Post requests can be made 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. Validators like JSONlint can save a lot of time.

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.

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

Types of content

There are seven types of content available through the API. 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.

Types of request

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.

Do contact us to let us know who to contact if we have further questions about your app's API usage.

Query

(array) This is equivalent to the 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 '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 sources with 'earthquake' in their name. (Note: this becomes more useful when limiting the search to a number of fields. To limit to only one field, using field:value - here "source:earthquake" - and omitting the fields parameter returns the same result. 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 titles with the words 'hot' AND 'cold'. (Compare with following query which uses 'OR'). 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 titles with the words 'hot' OR 'cold'. (Compare with previous query which uses 'AND'). The default operator is 'OR', so the parameter can be omitted. value, fields, operator

    GET:

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

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "hot cold",
          "fields": ["title"],
          "operator": "OR"
        },
      "preset": "latest"
    }
    
  • Query for exact values. Some fields (see fields tables for which ones) 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 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.

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:

  • 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"
        }
    }
    
  • 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"
        }
    }
    
  • 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"
        }
    }
    
  • 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
            }
          ]
        }
    }
    
  • Reports from June 2004. field, value from, value to

    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"
            }
        }
    }
    
  • Note: Dates must be URL-encoded for GET requests, but not for post requests. + should be written as %2B.

  • Reports tagged with France with 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"
            }
          ]
        }
    }
    
  • Multiple, nested conditions - Maps or Infographics of Afghanistan and all latest 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

(array) Facets are used on the ReliefWeb site to show a set of contents split by categories, status and/or date, with the count included. Facets are commonly used on e-commerce sites to break down product categories in an intuitive way. 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.

  • List the top 20 countries (by number of jobs) and the number of jobs for each. field, limit

    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
    }
    
  • List available themes for jobs (by default, returns the 10 most used themes). field

    GET:

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

    POST:

    https://api.reliefweb.int/v1/jobs?appname=apidoc
    {
      "facets": [
        {
          "field": "theme"
        }
      ],
      "limit": 0
    }
    
  • List top 10 sources (by number of reports) and the number of reports for each. (10 is the default limit for facets). field

    GET:

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

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "facets": [
        {
          "field": "source"
        }
      ],
      "limit": 0
    }
    
  • List bottom 10 countries (by number of 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
    }
    
  • List 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
    }
    
  • List all years (ordered ascending) and the number of reports for each. (Limit doesn't apply for date fields, so this doesn't default to 10). 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
    }
    
  • Filter facet - 5 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
    }
    
  • Multiple facets - top 5 countries 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]=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

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "facets": [
        {
          "name": "French",
          "field": "country",
          "filter":
            {
              "field": "country",
              "value": "France"
            },
          "sort": "count:desc",
          "limit": 5
        },
        {
          "name": "Spanish",
          "field": "country",
          "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:

  • The latest 3 reports.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&limit=3&preset=latest

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "limit": 3,
      "preset": "latest"
    }
    

Offset

(integer) How many results to skip. Mostly used for paging through results. Must be greater than 0, defaults to 0.

Example:

  • The next 3 reports after the limit example query.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&limit=3&offset=3&preset=latest

    POST:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "limit": 3,
      "offset": 3,
      "preset": "latest"
    }
    

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, but without a sort order, results may not be consistent.

For latest results, use preset=latest.

Example:

  • 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) Groups of fields to include in result.

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

Example:

  • Reports with list profile and including the original publication date.

    GET:

    https://api.reliefweb.int/v1/reports?appname=apidoc&profile=list&fields[include][]=date.original

    POST:

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

Preset

(string) Already prepared combinations of fields to display, filters on the status field and sort settings to use in different use-cases.

  • minimal: Default setting, applies sensible status filters for most requests.
  • analysis: Used for ReliefWeb Trends, includes expired jobs and archived disasters.
  • latest: Sorts by date for appropriate content types. Countries and sources sorted by id. Use this for list requests.

Presets for each content type are specified in the fields table. The minimal preset for sources looks like this:

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

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:

https://api.reliefweb.int/v1/jobs?preset=latest&filter[field]=status&filter[value]=expired
          

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.

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.

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 any 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

    Response:

    {
      "href":"https:\/\/api.reliefweb.int\/v1\/reports?profile=full&limit=1",
      "time":28,
      "links":
        {
          "self":
            {
              "href":"https:\/\/api.reliefweb.int\/v1\/reports?offset=0&limit=1&preset=minimal"
            },
          "next":
            {
              "href":"https:\/\/api.reliefweb.int\/v1\/reports?offset=1&limit=1&preset=minimal"
            }
        },
      "totalCount":666196,
      "count":1,
      "data":
        [
          {
            "id":"1211236",
            "score":1,
            "href":"https:\/\/api.reliefweb.int\/v1\/reports\/1211236",
            "fields":
              {
                "id":1211236,
                "title":"Women in Mali demand equal role in Peace Accords",
                "status":"published",
                "body":"**Before and after reaching a peace agreement <---snip--->",
                "origin":"http:\/\/www.unwomen.org\/en\/news\/stories\/2015\/10\/women-in-mali-demand-equal-role-in-peace-accords",
                "primary_country":
                  {
                    "href":"https:\/\/api.reliefweb.int\/v1\/countries\/149",
                    "id":149,
                    "name":"Mali",
                    "iso3":"mli",
                    "location":[-1.25,17.35]
                  },
                "country":
                  [
                    {
                      "href":"https:\/\/api.reliefweb.int\/v1\/countries\/149",
                      "id":149,
                      "name":"Mali",
                      "iso3":"mli",
                      "location":[-1.25,17.35],
                      "primary":true
                    }
                  ],
                "source":
                  [
                    {
                      "href":"https:\/\/api.reliefweb.int\/v1\/sources\/4512",
                      "id":4512,
                      "name":"UN Women",
                      "shortname":"UN Women",
                      "homepage":"http:\/\/www.unwomen.org\/",
                      "type":{
                        "id":272,
                        "name":"International Organization"
                      }
                    }
                  ],
                "language":
                  [
                    {
                      "id":267,
                      "name":"English",
                      "code":"en"
                    }
                  ],
                "theme":
                  [
                    {
                      "id":4599,
                      "name":"Peacekeeping and Peacebuilding"},
                    },
                    {
                      "id":4600,
                      "name":"Protection and Human Rights"
                    }
                  ],
                "format":
                  [
                    {
                      "id":8,
                      "name":"News and Press Release"
                    }
                  ],
                "disaster":
                  [
                    {
                      "id":9946,
                      "name":"Sahel Crisis: 2011-2016",
                      "glide":"OT-2011-000205-NER",
                      "type":
                        [
                          {
                            "id":4672,
                            "name":"Drought",
                            "code":"DR",
                            "primary":true
                          },
                          {
                            "id":5042,
                            "name":"Other",
                            "code":"OT"
                          }
                        ]
                    }
                  ],
                "disaster_type":
                  [
                    {
                      "id":4672,
                      "name":"Drought",
                      "code":"DR"
                    },
                    {
                      "id":5042,
                      "name":"Other",
                      "code":"OT"
                    }
                  ],
                "vulnerable_groups":
                  [
                    {
                      "id":6875,
                      "name":"Women"
                    }
                  ],
                "url":"http:\/\/reliefweb.int\/node\/1211236",
                "body-html":"Before and after <---snip--->",
                "date":
                  {
                    "original":"2015-10-10T22:35:04+00:00",
                    "changed":"2015-10-10T22:35:04+00:00",
                    "created":"2015-10-10T22:35:04+00:00"
                  }
              }
          }
        ]
    }
    

    Commented response schema:

    {
      "href": // url of request - Post request bodies aren't reflected here.
      "time": // milliseconds 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": // Results returned in this json object.
      "data": // Array of 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 changed through presets and fields parameter.
              {
                "id": // ReliefWeb id of resource. As above.
                "title": // Title of report.
                "status": // Always 'published' for reports. Has other information for other content types.
                "body": // Markdown formatted body field.
                "origin": // Original url for report, at time of publishing.
                "primary_country": // The key country for this report. 'World' for very general reports.
                  {
                    "href": // API url for more information on this country.
                    "id": // ReliefWeb id of this country.
                    "name": // Country name.
                    "iso3": // Country ISO3 code.
                    "location": // Country coordinates.
                  },
                "country": // Array of other countries connected with report. Details of each as primary country,
                "source":
                  [
                    {
                      "href": // API url for more information on this source.
                      "id": // ReliefWeb id of this source.
                      "name": // Source name.
                      "shortname": // Shortname of source, if there is one.
                      "longname": // Longer name of source, if there is one.
                      "homepage": // Url of homepage of source.
                      "type":{
                        "id": // ReliefWeb id of this source type.
                        "name": // Source type name.
                      }
                    }
                  ],
                "language": // Language of the report.
                  [
                    {
                      "id": // ReliefWeb id of this language.
                      "name": // Language name.
                      "code": // Language code.
                    }
                  ],
                "theme": // Array of themes covered in this report.
                  [
                    {
                      "id": // ReliefWeb id of this theme.
                      "name": // Theme name
                    }
                  ],
                "format": // Array of formats of this report.
                  [
                    {
                      "id": // ReliefWeb id of this format.
                      "name": // Format name
                    }
                  ],
                "disaster": // Array of disasters associated with this report.
                  [
                    {
                      "id": // ReliefWeb id of this disaster.
                      "name": // Disaster name.
                      "glide": // GLIDE number of this disaster.
                      "type": // Array of disaster types associated with this disaster.
                        [
                          {
                            "id": // ReliefWeb id of disaster type of disaster.
                            "name": // Name of disaster type.
                            "code": // Code of disaster type.
                            "primary": // Whether this is the primary disaster type for the disaster.
                          }
                        ]
                    }
                  ],
                "disaster_type": // Array of disaster types associated with this report.
                  [
                    {
                      "id": // ReliefWeb id of disaster type of disaster.
                      "name": // Name of disaster type.
                      "code": // Code of disaster type.
                    }
                  ],
                "vulnerable_groups":
                  [
                    {
                      "id": // ReliefWeb id of vulnerable groups affected by this report.
                      "name": // Name of vulnerable group.
                    }
                  ],
                "url": // Url of this report on ReliefWeb.
                "body-html": // HTML-formatted body field.
                "date":
                  {
                    "original": // Date report published by source.
                    "changed": // Date report modified by ReliefWeb.
                    "created": // Date report published by ReliefWeb.
                  }
              }
          }
        ]
    }
    

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 value:

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

    Response:

    {
      "status": 400,
      "time": 7,
      "error":
        {
          "type": "UnexpectedValueException",
          "message": "Invalid \"limit\" specified. Valid values are between 0 and 1000"
        }
    }
    

  • Non-encoded time value in GET request:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[field]=date.created&filter[value][from]=2004-06-01T00:00:00+00:00

    Response:

    {
      "status": 400,
      "time": 24,
      "error":
        {
          "type": "UnexpectedValueException",
          "message": "Invalid range 'from' value for field 'date.created'. It must be an ISO 8601 date."
        }
    }
    

  • Invalid parameter:

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

    Response:

    {
      "status":400,
      "time":21,
      "error":
        {
          "type":"UnexpectedValueException",
          "message":"Invalid query field 'field'. Valid values are 'value', 'operator', 'fields'."
        }
    }
    

  • Invalid syntax:

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

    Response:

    {
      "status":400,
      "time":25,
      "error":
        {
          "type":"UnexpectedValueException",
          "message":"Invalid query attribute 'fields'. It must be an array of string field names."
        }
    }
    

Examples, tips, suggestions

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

  • 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
  • How many reports have been published from IFRC?

    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
  • 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
  • To help craft query filters, use the search options box as a GUI.

    Let's take a complicated query, and work out how to translate it.

    This query is for reports in English in 2015, relating to Refugees, concerning Bolivia or Paraguay but not Argentina and Chile:

    http://reliefweb.int/updates?advanced-search=(C39.C186)_!(C22_C57)_(VG6874)_(L267)_(DA20150101-20151231)

    Click the link to see how easy it is to refine the query on the ReliefWeb site.

    To translate, updates on the site are reports for the API.

    Thus, our familiar base:

    https://api.reliefweb.int/v1/reports

    When there is only one value inside a group, it translates to a simple filter. Otherwise it's a conditional filter with multiple filters and an operator.

    An underscore means AND, a dot means OR, an exclamation point means "Negate". Parentheses delimit groups (WITH, WITHOUT) with either AND or OR as inside operator.

    Thus:

    FilterMeaning
    (C39.C186) WITH country 39 (Bolivia) OR country 186 (Paraguay).
    _!(C22_C57) AND WITHOUT country 22 (Argentina) OR country 57 (Chile)
    _(VG6874) AND WITH vulnerable group 6874 (refugees)
    _(L267) AND WITH language 267 (English)
    _(DA20150101-20151231) AND WITH posting date in 2015.

    For all fields except dates, the value is the taxonomy id (".id" subfield in the API). The field abbreviations are included in the fields table.

    Dates -

    DA[optionalFromDate]-[optionalToDate]
    are in the format YYYYMMDD and should be converted to ISO 8601 dates.

    Conversion

    As a GET request this becomes pretty long:

    https://api.reliefweb.int/v1/reports?appname=apidoc&filter[conditions][0][conditions][0][conditions][0][field]=country.id&filter[conditions][0][conditions][0][conditions][0][value][0]=39&filter[conditions][0][conditions][0][conditions][0][value][1]=186&filter[conditions][0][conditions][0][conditions][0][operator]=OR&filter[conditions][0][conditions][0][conditions][1][field]=country.id&filter[conditions][0][conditions][0][conditions][1][value][0]=22&filter[conditions][0][conditions][0][conditions][1][value][1]=57&filter[conditions][0][conditions][0][conditions][1][operator]=OR&filter[conditions][0][conditions][0][conditions][1][negate]=true&filter[conditions][0][conditions][0][conditions][2][field]=vulnerable_groups.id&filter[conditions][0][conditions][0][conditions][2][value][]=6874&filter[conditions][0][conditions][0][conditions][3][field]=language.id&filter[conditions][0][conditions][0][conditions][3][value][]=267&filter[conditions][0][conditions][0][operator]=AND&filter[conditions][0][conditions][1][field]=date.created&filter[conditions][0][conditions][1][value][from]=2015-01-01T00:00:00%2B00:00&filter[conditions][0][conditions][1][value][to]=2015-12-31T23:59:59%2B00:00&filter[conditions][0][operator]=AND

    So here it is, easier to read and debug, as a POST request:

    https://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "conditions":
            [
              {
                "conditions":
                  [
                    {
                      "field": "country.id",
                      "value": ["39"]
                    },
                    {
                      "field": "country.id",
                      "value": ["186"]
                    }
                  ],
                "operator": "OR"
              },
              {
                "conditions":
                  [
                    {
                      "field": "country.id",
                      "value": ["22"]
                    },
                    {
                      "field": "country.id",
                      "value": ["57"]
                    }
                  ],
                "operator": "AND",
                "negate": true
              },
              {
                "field": "vulnerable_groups.id",
                "value": ["6874"]
              },
              {
                "field": "language.id",
                "value": ["267"]
              },
              {
                "conditions":
                  [
                    {
                      "field": "date.created",
                      "value":
                        {
                          "from": "2015-01-01T00:00:00+00:00",
                          "to": "2015-12-31T23:59:59+00:00"
                        }
                    }
                  ],
                "operator": "AND"
              }
            ],
          "operator": "AND"
        }
    }
    

    When there is a OR WITH or OR WITHOUT group then it combines with all the groups before it into a conditional filter with a OR operator.

Fields tables

Use tabs to see lists of fields by content type.The summary tab shows all fields, and which content types they are used in.

The tables shows the names of fields with a short description, its type, whether it can be used for search, sorts and facets or with the "exact" qualifier, the abbreviation used in advanced search and its preset settings.

NameDescriptionTypeAttributesAbbreviationContent Types
bodystringsearchableRJT
body-htmlstringRJT
career_categoriesdefaults to career_categories.namearrayJT
career_categories
.id
integersearchable facetableCCJT
career_categories
.name
Link for valuesstringsearchable facetable exactJT
citydefaults to city.namearrayJT
city.namestringsearchable facetable exactJT
content_typeContent types published from this sourcearraysortable searchableS
countrydefaults to country.namearrayRJTDS
country.idId for country used by ReliefWebintegersearchable facetableCRJTDS
country.iso3ISO 3166-1 alpha-3 codestringsearchable facetable exactRJTDS
country.namestringsearchable facetable exactRJTDS
country.primaryFlag to indicate this is the primary countrybooleanRJTDS
country.shortnamestringsearchable facetable exactRJTDS
costfree or fee-basedstringsearchable facetableT
currentFlag to indicate the country has an active situation – deprecated for disasters.booleansortable facetableCD
datedefaults to date.createdobjectsortable facetableRJD
date.changedDate entry modified on ReliefWeb (ISO 8601)datesortable facetableRJT
date.closingDate job closes to applicants (ISO 8601)datesortable facetableDCJ
date.createdDate entry created on ReliefWeb (ISO 8601)datesortable facetableDARJTD
date.endDate training ends (ISO 8601)datesortable facetableDET
date.originalDate entry first published by original source (ISO 8601)datesortable facetableDOR
date.registrationDate registration closes (ISO 8601)datesortable facetableDRT
date.startDate training starts (ISO 8601)datesortable facetableDST
descriptionstringsearchableCDS
description-htmlstringCDS
disasterdefaults to disaster.namearrayR
disaster.idId for disaster used by ReliefWebintegersearchable facetableDR
disaster.nameName assigned to the disaster based on the ReliefWeb disaster naming conventionstringsearchable facetable exactR
disaster.glideGlobal IDEntifier number (GLIDE) of the disasterstringsearchable facetableR
disaster.typeDisaster type of the associated disaster. Note this may be different to the `disaster_type` of a report. Defaults to disaster.type.namearrayR
disaster.type.codeCode for the disaster type of the associated disaster.stringsearchable facetableR
disaster.type.idId for the disaster type of the associated disaster.integersearchable facetableR
disaster.type.nameLink for valuesstringsearchable facetable exactR
disaster.type.primaryWhether this is the primary disaster type for the associated disaster.booleanR
disaster_typedefaults to disaster_type.namestringR
disaster_type.codearraysearchable facetableR
disaster_type.idId for disaster type used by ReliefWebintegersearchable facetableDTR
disaster_type.nameLink for valuesstringsearchable facetable exactR
experiencedefaults to experience.namearrayJ
experience.idId for years of experience used by ReliefWebintegersearchable facetableEJ
experience.nameLink for values.stringsearchable facetable exactJ
featuredefaults to feature.namearrayR
feature.idId for feature used by ReliefWebintegersearchable facetableR
feature.nameLink for values.stringsearchable facetable exactR
featuredFlag to indicate if the country is featured on ReliefWeb home pagebooleansortable facetableCD
filedefaults to file.idarrayRJT
file.copyrightstringsearchableR
file.descriptionstringsearchableRJT
file.filenamestringRJT
file.idId for file used by ReliefWebintegersearchableRJT
file.mimetypestringRJT
file.previewShortcut for preview image of file attachment - defaults to file.preview.urlarrayR
file.preview
.url
Link to the original preview imagestringR
file.preview
.url-large
Link to a large preview image with a width of 680pxstringR
file.preview
.url-small
Link to a small preview image with a width of 200pxstringR
file.preview
.url-thumb
Link to a thumbnail preview image with a maximum width of 220px and a maximum height of 100pxstringR
file.urlstringRJT
formatdefaults to format.namearrayRT
format.idId for format used by ReliefWebintegersearchable facetableFRT
format.nameValues depend on content typestringsearchable facetable exactRT
fts_idId for organization used by FTSintegersortable searchableS
glideGlobal IDEntifier number (GLIDE) of the disasterstringsortable searchable exactD
headlinedefaults to headline.titlearrayR
headline.featuredstringsortable searchable facetableR
headline.imagedefaults to headline.image.idarrayR
headline.image
.caption
stringsearchableR
headline.image
.copyright
stringsearchableR
headline.image
.filename
stringR
headline.image
.id
Id of headline image used by ReliefWebintegersearchableR
headline.image
.mimetype
stringR
headline.image
.url
stringR
headline.summarySummary of body, if report is selected as headline. Typically 180-190 characters longstringsearchableR
headline.titleHeadline text, if report is selected as headline. Typically 100-120 characters longstringsortable searchableR
homepagestringsearchableS
how_to_applystringsearchableJ
how_to_apply-htmlstringJ
how_to_registerstringsearchableT
how_to_register-htmlstringT
idUnique id for entity used by ReliefWebintegersortable searchableRJTCDS
imagedefaults to image.idarrayR
image.captionstringsearchableR
image.copyrightstringsearchableR
image.filenamestringR
image.idId for image used by ReliefWebintegersearchableR
image.mimetypestringR
image.urlLink to the original imagestringR
image.url-largeLink to a large image with a width of 680pxstringR
image.url-smallLink to a small image with a width of 200pxstringR
image.url-thumbLink to a thumbnail image with a maximum width of 220px and a maximum height of 100pxstringR
iso3ISO 3166-1 alpha-3 codestringsortable searchable exactC
languagedefaults to language.namearrayRJT
language.codestringsearchable facetableRJT
language.idId for language used by ReliefWebintegerfacetable exactLRJT
language.nameLink for values.stringsearchable facetable exactRJT
longnamestringsortable searchable exactS
namestringsortable searchable exactCDS
ocha_productdefaults to ocha_product.namearrayR
ocha_product.idId for OCHA product used by ReliefWebintegersearchable facetableR
ocha_product.nameLink for valuesstringsearchable facetable exactR
originUrl of original report at date.createdstringR
primary_countrydefaults to primary_country.namearrayRD
primary_country
.id
Id for primary country used by ReliefWebintegersortable searchable facetablePCRD
primary_country
.iso3
ISO 3166-1 alpha-3 codestringsortable searchable facetable exactRD
primary_country
.name
Link for valuesstringsortable searchable facetable exactRD
primary_country
.shortname
stringsortable searchable facetable exactRD
primary_typedefaults to primary_type.namearrayD
primary_type.idId for disaster type used by ReliefWebintegersearchable facetableTYD
primary_type.namestringsearchable facetable exactD
related_glideGlobal IDEntifier number (GLIDE) of related disastersarraysearchable exactD
shortnamestringsortable searchable exactCS
sourcedefaults to source.namearrayRJT
source.homepageURL of the source's primary websitestringsearchableRJT
source.idId for source used by ReliefWebintegersearchable facetableSRJT
source.longnameOfficial name of the source if different from source.namestringsearchable facetable exactRJT
source.namestringsearchable facetable exactRJT
source.shortnameShort name of the source, typically an acronym e.g. UNICEFstringsearchable facetable exactRJT
source.typedefaults to source.type.namearrayRJT
source.type.idId for source type used by ReliefWebintegersearchable facetableSTRJT
source.type.nameValues depend on content typestringsearchable facetable exactRJT
statusValues depend on content typestringsearchable facetableRJTCS
themedefaults to theme.namearrayRJT
theme.idId for theme used by ReliefWebintegersearchable facetableTRJT
theme.nameLink for valuesstringsearchable facetable exactRJT
titleTitlestringsortable searchable exactRJT
training_languageLanguage training is held in, defaults to training_language.namestringfacetable exactT
training_language.idId of language training is held inintegerfacetableT
training_language.nameLink for values.stringfacetable exactT
training_language.codeCode of language training is held instringfacetable exactT
typedefaults to type.namearrayJTDS
type.codestringsortable searchable facetableD
type.idId for entity type used by ReliefWebintegersearchable facetableTYJTDS
type.nameValues depend on content typestringsearchable facetable exactJTDS
type.primarybooleanD
urlCanonical url of entitystringRJTCDS
urlFriendly' url of entitystringRJTCDS
vulnerable_groupsdefaults to vulnerable_groups.namearrayR
vulnerable_groups
.id
Id for vulnerable group used by ReliefWebintegersearchable facetableVGR
vulnerable_groups
.name
Link for valuesstringsearchable facetable exactR
NameDescriptionTypeAttributesAbbreviationPreset settings
bodyMain text in Markdown formatstringsearchablequery: analysis latest
body-htmlMain text in HTML formatstring
countryShortcut for country - defaults to country.namearrayquery: analysis latest
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 facetableDAsort: latest
date.originalDate entry first published by original source (ISO 8601)datesortable facetableDO
disasterShortcut for related disaster - defaults to disaster.namearrayquery: analysis latest
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.namearraysearchable facetable exact
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.namearrayquery: analysis latest
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.namearray
feature.idId for feature used by ReliefWebintegersearchable facetable
feature.nameLink for values.stringsearchable facetable exact
fileFile attachment shortcut - defaults to file.idarray
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.urlarray
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.namearray
format.idId of content format used by ReliefWebintegersearchable facetableF
format.nameLink for valuesstringsearchable facetable exactquery: analysis latest
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 longstringsearchablequery: analysis latest
headline.titleHeadline text, if report is selected as headline. Typically 100-120 characters longstringsortable searchablequery: analysis latest
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.namearrayquery: analysis latest
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.namearray
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.namearrayquery: analysis latest
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.namearrayquery: analysis latest
source.idId for source used by ReliefWebintegersearchable facetableS
source.nameCommon name of sourcestringsearchable facetable exact
source.shortnameShort name of the source, typically an acronym e.g. UNICEFstringsearchable facetable exact
source.longnameOfficial name of the source if different from source.namestringsearchable facetable exact
source.homepageURL of the source's primary websitestringsearchable
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 facetablequery: analysis filter: analysis ['published', 'to-review'] latest ['published', 'to-review'] minimal ['published']
themeShortcut for theme - defaults to theme.namearray
theme.idId of theme used by ReliefWebintegersearchable facetableT
theme.nameLink for valuesstringsearchable facetable exactquery: analysis latest
titleTitle of reportstringsortable searchable exactquery: analysis latest minimal
urlCanonical urlstring
url_aliasFriendly' url of the reportstringsearchable
vulnerable_groupsShortcut for vulnerable groups - defaults to vulnerable_groups.namearrayquery: analysis latest
vulnerable_groups
.id
Id for vulnerable groups used by ReliefWebintegersearchable facetableVG
vulnerable_groups
.name
Link for valuesstringsearchable facetable exact
NameDescriptionTypeAttributesAbbreviationPreset settings
countryShortcut for country - defaults to country.namearrayquery: analysis latest
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.createdobject
date.createdDate entry created on ReliefWeb (ISO 8601)datesortable facetableDAsort: latest
descriptionDescription of the disaster in Markdown formatstringsearchablequery: analysis latest
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 exactquery: analysis latest
idUnique id of disaster used by ReliefWebintegersortable searchable
namestringsortable searchable exactquery: analysis latest minimal
primary_countryShortcut for primary country - defaults to primary_country.namearray
primary_country
.id
Id of primary country used by ReliefWebintegersortable searchable facetablePC
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.namearray
primary_type.idId for primary disaster type used by ReliefWebintegersearchable facetableTY
primary_type.nameName of primary disaster typestringsearchable facetable exact
related_glideRelated Global IDEntifier number (GLIDE)arraysearchable exact
statuscurrent', 'alert', 'past'stringsearchable facetablequery: analysis filter: analysis ['alert', 'alert-archive', 'archive', 'current', 'past'] latest ['alert', 'current', 'past'] minimal ['alert', 'current', 'past']
typeShortcut for disaster type - defaults to type.namearrayquery: analysis latest
type.codeCode of disaster typestringsortable searchable facetable
type.idId of disaster type used by ReliefWebintegersearchable facetableTY
type.nameLink for valuesstringsearchable facetable exact
type.primaryWhether disaster type is primary or notboolean
urlCanonical urlstring
url_aliasFriendly' url of the disasterstringsearchable
NameDescriptionTypeAttributesAbbreviationPreset settings
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 searchablesort: latest
iso3ISO 3166-1 alpha-3 codestringsortable searchable exactquery: analysis latest
nameCountry name in Englishstringsortable searchable exactquery: analysis latest minimal
shortnameShort name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'stringsortable searchable exactquery: analysis latest
statusWhether country has an active situationstringsearchable facetablequery: analysis
urlCanonical urlstring
url_aliasFriendly' url of the countrystringsearchable
video_playlistPlaylist id of curated videos about the countrystring
NameDescriptionTypeAttributesAbbreviationPreset settings
bodyDescription of job in Markdown formatstringsearchablequery: analysis latest
body-htmlDescription of job in HTML formatstring
career_categoriesShortcut for career categories - defaults to career_categories.namearrayquery: analysis latest
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.namearray
city.nameName of city in Englishstringsearchable facetable exact
countryShortcut for country - defaults to country.namearrayquery: analysis latest
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 facetableDAsort: analysis
experienceShortcut for experience requirement - defaults to experience.namearray
experience.idId for experience requirement used by ReliefWebintegersearchable facetableE
experience.nameLink for values.stringsearchable facetable exact
fileShortcut for file attachment - defaults to file.idarray
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 formatstringsearchablequery: analysis latest
how_to_apply-htmlApplication instructions for the job in HTML formatstring
idUnique id of job used by ReliefWebintegersortable searchable
sourceShortcut for source - defaults to source.namearrayquery: analysis latest
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.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 facetablequery: analysis filter: analysis ['published', 'expired'] minimal ['published']
themeShortcut for theme - defaults to theme.namearrayquery: analysis latest
theme.idId for theme used by ReliefWebintegersearchable facetableT
theme.nameLink for valuesstringsearchable facetable exact
titleJob titlestringsortable searchable exactquery: analysis latest minimal
typeShortcut for type - defaults to type.namearray
type.idId for job type used by ReliefWebintegersearchable facetableTY
type.nameLink for valuesstringsearchable facetable exact
urlCanonical urlstring
url_aliasFriendly' url of the jobstringsearchable
NameDescriptionTypeAttributesAbbreviationPreset settings
bodyTraining description in Markdown formatstringsearchablequery: analysis latest
body-htmlTraining description in HTML formatstring
career_categoriesShortcut for career categories - defaults to career_categories.namearrayquery: analysis latest
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.namearray
city.nameName of city in Englishstringsearchable facetable exact
costfree or fee-basedstringsearchable facetable
countryShortcut for country - defaults to country.namearrayquery: analysis latest
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 facetablesort: latest
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.idarray
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.namearrayquery: analysis latest
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.namearray
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.namearrayquery: analysis latest
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.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 facetablequery: analysis filter: analysis ['published', 'expired'] latest ['published'] minimal ['published']
themeShortcut for theme - defaults to theme.namearrayquery: analysis latest
theme.idId for theme used by ReliefWebintegersearchable facetableT
theme.nameLink for valuesstringsearchable facetable exact
titleTitle of coursestringsortable searchable exactquery: analysis latest minimal
training_languageLanguage training is held in, defaults to training_language.namestringfacetable exact
training_language.idId of language training is held inintegerfacetable
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.namearray
type.idId for training type used by ReliefWebintegersearchable facetableTY
type.nameLink for valuesstringsearchable facetable exact
urlCanonical urlstring
url_aliasFriendly' url of the trainingstringsearchable
NameDescriptionTypeAttributesAbbreviationPreset settings
content_typeContent types published from this sourcearraysortable searchable
countryShortcut for country - defaults to country.namearray
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
fts_idId number for organization used by FTSnumbersortable searchable
homepageUrl of organizationstringsearchable
idUnique id for source used by ReliefWebintegersortable searchablesort: latest
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 exactquery: analysis latest
nameName of sourcestringsortable searchable exactquery: analysis latest minimal
shortnameName of the source in abbreviated format, where applicablestringsortable searchable exactquery: analysis latest
statusWhether source is active or notstringsearchable facetablequery: analysis filter: analysis ['active', 'inactive'] latest ['active', 'inactive'] minimal ['active', 'inactive']
typeShortcut for type of organization - defaults to type.namearray
type.idId of organization type used by ReliefWebintegersearchable facetableTY
type.nameLink for valuesstringsearchable facetable exact
urlCanonical urlstring
url_aliasFriendly' url of the sourcestringsearchable