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:
"http://"
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:

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

or as a body to a POST request:

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

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 'http://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.

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 documented in line with the OpenAPI Specification (also known as Swagger). You can explore this here: http://api.reliefweb.int/v1/swagger/api

Types of content

There are six types of content available through the API. reports, disasters, countries, jobs, training and sources.

  • 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.

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:

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

      POST:

      http://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:

      http://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) An optional field to help ReliefWeb monitor API usage and adapt it to user needs.

The name you choose should give us some idea of what the call is for. For example, the ReliefWeb Headlines mobile app uses rw-app-headlines and humanitarianresponse.com uses humanitarianresponse.com. 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. Specifying a field without a value 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.

Examples:

  • Query for 'earthquake'. value

    GET:

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

    POST:

    http://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "earthquake"
        }
    }
    
  • Query for sources with 'earthquake' in their name. value, fields

    GET:

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

    POST:

    http://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'. value, fields, operator

    GET:

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

    POST:

    http://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'. value, fields, operator

    GET:

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

    POST:

    http://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "query":
        {
          "value": "hot cold",
          "fields": ["title"],
          "operator": "OR"
        },
      "preset": "latest"
    }
    
  • Note: for many queries, because results are ordered by relevance (see the result field Score), the results for AND and OR can be almost identical. Using sort[]=date:desc or preset=latest will make the difference more explicit.

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

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

    POST:

    http://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "field": "headline"
        }
    }
    
  • Reports tagged with France. value, field

    GET:

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

    POST:

    http://api.reliefweb.int/v1/reports?appname=apidoc
    {
      "filter":
        {
          "field": "country",
          "value": ["France"]
        }
    }
    
  • Reports tagged with France or Spain. value, field, operator

    GET:

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

    POST:

    http://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:

    http://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:

    http://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:

    http://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:

    http://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:

    http://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:

    http://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:

    http://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:

    http://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
  • 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:

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

    POST:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

    http://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:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

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

    POST:

    http://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:

http://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:

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

    POST:

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

    GET:

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

    POST:

    http://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:

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

    POST:

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

    GET:

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

    POST:

    http://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:

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

    POST:

    http://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:

    http://api.reliefweb.int/v1/reports?profile=full&limit=1

    Response:

    {
      "href":"http:\/\/api.reliefweb.int\/v1\/reports?profile=full&limit=1",
      "time":28,
      "links":
        {
          "self":
            {
              "href":"http:\/\/api.reliefweb.int\/v1\/reports?offset=0&limit=1&preset=minimal"
            },
          "next":
            {
              "href":"http:\/\/api.reliefweb.int\/v1\/reports?offset=1&limit=1&preset=minimal"
            }
        },
      "totalCount":666196,
      "count":1,
      "data":
        [
          {
            "id":"1211236",
            "score":1,
            "href":"http:\/\/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":"http:\/\/api.reliefweb.int\/v1\/countries\/149",
                    "id":149,
                    "name":"Mali",
                    "iso3":"mli",
                    "location":[-1.25,17.35]
                  },
                "country":
                  [
                    {
                      "href":"http:\/\/api.reliefweb.int\/v1\/countries\/149",
                      "id":149,
                      "name":"Mali",
                      "iso3":"mli",
                      "location":[-1.25,17.35],
                      "primary":true
                    }
                  ],
                "source":
                  [
                    {
                      "href":"http:\/\/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:

    http://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:

    http://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:

    http://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:

    http://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.

  • How many reports have been published from IFRC?

    Look at the totalcount from:

    http://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:

    http://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:

    http://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.
    • 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:

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

      http://api.reliefweb.int/v1/reports?appname=apidoc&query[fields][]=title&query[value]=hot weather
      http://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:

      http://api.reliefweb.int/v1/reports?appname=apidoc&sort[]=date:desc&query[fields][]=title&query[value]=hot AND cold&query[operator]=OR
      http://api.reliefweb.int/v1/reports?appname=apidoc&sort[]=date:desc&query[fields][]=title&query[value]=hot OR cold&query[operator]=OR
      http://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:

      http://api.reliefweb.int/v1/reports?appname=apidoc&fields[include][]=source.name&query[value]=title:climate
      http://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:

      http://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:

    http://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:

    http://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:

    http://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.

Field 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, the abbreviation used in advanced search and its preset settings.

NameDescriptionTypeSortable/ Searchable/ FacetableAdvanced search abbreviationContent types
body  stringsearchable RJT
body-html  string RJT
career_categoriesdefaults to career_categories.namestring searchable facetable JT
career_categories
.id
 integer searchable facetableCCJT
career_categories
.name
Link for valuesstring searchable facetable JT
citydefaults to city.namestring searchable facetable JT
city.id integer searchable facetable JT
city.name string searchable facetable JT
content_typeContent types published from this sourcestring sortable searchable S
country defaults to country.namestring searchable facetable RJTDS
country.id Id for country used by ReliefWeb integer searchable facetableCRJTDS
country.primary Flag to indicate this is the primary countryboolean  RJTDS
country.name  string searchable facetable RJTDS
country.shortname  string searchable facetable RJTDS
country.iso3 ISO 3166-1 alpha-3 codestring searchable facetable RJTDS
costfree or fee-basedstring searchable facetable T
currentFlag to indicate the country has an active situation – deprecated for disasters.boolean sortable facetable CD
date defaults to date.createddate sortable facetable RJD
date.changed Date entry modified on ReliefWeb (ISO 8601)date sortable facetable RTJ
date.closingDate job closes to applicants (ISO 8601)datesortable facetableDCJ
date.created Date entry created on ReliefWeb (ISO 8601)date sortable facetableDARTJD
date.endDate training ends (ISO 8601)datesortable facetableDET
date.original Date entry first published by original source (ISO 8601)date sortable facetableDOR
date.registrationDate registration closes (ISO 8601)datesortable facetableDRT
date.startDate training starts (ISO 8601)datesortable facetableDST
description stringsearchable CDS
description-html string CDS
disaster defaults to disaster.namestring searchable facetable R
disaster.id Id for disaster used by ReliefWeb integer searchable facetableDR
disaster.name Name assigned to the disaster based on the ReliefWeb disaster naming conventionstring searchable facetable R
disaster.glide Global IDEntifier number (GLIDE) of the disasterstring searchable facetable R
disaster_type defaults to disaster_type.namestring searchable facetable R
disaster_type.code  string searchable facetable R
disaster_type.id Id for disaster type used by ReliefWeb integer searchable facetableDTR
disaster_type.name Link for valuesstring searchable facetable R
experiencedefaults to experience.namestring searchable facetable J
experience.idId for years of experience used by ReliefWeb integer searchable facetableEJ
experience.nameTime range of experience required for positionstring searchable facetable  J
feature defaults to feature.namestring searchable facetable R
feature.id Id for feature used by ReliefWeb integer searchable facetable R
feature.name Featured contentstring searchable facetable R
featuredFlag to indicate if the country is featured on ReliefWeb home pageboolean sortable facetable CD
file defaults to file.idinteger searchable RJT
file.copyright  string searchable R
file.description  string searchable RJT
file.filename  string  RJT
file.id Id for file used by ReliefWeb integer searchable RJT
file.mimetype  string  RJT
file.preview  string  R
file.preview
.url
Link to the original preview imagestring  R
file.preview
.url-large
Link to a large preview image with a width of 680pxstring  R
file.preview
.url-small
Link to a small preview image with a width of 200pxstring  R
file.preview
.url-thumb
Link to a thumbnail preview image with a maximum width of 220px and a maximum height of 100pxstring  R
file.url  string  RJT
format defaults to format.namestring searchable facetable RT
format.id Id for format used by ReliefWeb integer searchable facetableFRT
format.name Values depend on content typestring searchable facetable RT
fts_idId for organization used by FTSinteger sortable searchable S
glideGlobal IDEntifier number (GLIDE) of the disasterstring sortable searchable D
headline defaults to headline.titlestring sortable searchable R
headline.featured  string sortable searchable facetable R
headline.image defaults to headline.image.idinteger searchable R
headline.image
.caption
 string searchable R
headline.image
.copyright
 string searchable R
headline.image
.filename
 string  R
headline.image
.id
Id of headline image used by ReliefWeb integer searchable R
headline.image
.mimetype
 string  R
headline.image
.url
 string  R
headline.summary Summary of body, if report is selected as headline. Typically 180-190 characters longstring searchable R
headline.title Headline text, if report is selected as headline. Typically 100-120 characters longstring sortable searchable R
homepage string searchable S
how_to_apply stringsearchable J
how_to_apply-html string J
how_to_register stringsearchable T
how_to_register-html string T
id Unique id for entity used by ReliefWeb integer sortable searchable  RJTCDS
image defaults to image.idinteger searchable R
image.caption  string searchable R
image.copyright  string searchable R
image.filename  string  R
image.id Id for image used by ReliefWeb integer searchable R
image.mimetype  string  R
image.url Link to the original imagestring  R
image.url-large Link to a large image with a width of 680pxstring  R
image.url-small Link to a small image with a width of 200pxstring  R
image.url-thumb Link to a thumbnail image with a maximum width of 220px and a maximum height of 100pxstring  R
iso3ISO 3166-1 alpha-3 codestring sortable searchable C
language defaults to language.namestring searchable facetable RJT
language.code  string searchable facetable RJT
language.id Id for language used by ReliefWeb integer facetableLRJT
language.name  string searchable facetable RJT
longname string sortable searchable S
name string sortable searchable CDS
ocha_product defaults to ocha_product.namestring searchable facetable R
ocha_product.id Id for OCHA product used by ReliefWeb integer searchable facetable R
ocha_product.name Link for valuesstring searchable facetable R
origin Url of original report at date.createdstring  R
primary_country defaults to primary_country.namestring searchable facetable RD
primary_country
.id
Id for primary country used by ReliefWeb integer sortable searchable facetablePCRD
primary_country
.iso3
ISO 3166-1 alpha-3 codestring sortable searchable facetable RD
primary_country
.name
Link for valuesstring sortable searchable facetable RD
primary_country
.shortname
 string sortable searchable facetable RD
primary_typedefaults to primary_type.namestring searchable facetable D
primary_type.idId for disaster type used by ReliefWeb integer searchable facetableTYD
primary_type.name string searchable facetable D
related_glideGlobal IDEntifier number (GLIDE) of related disasters string searchable D
shortname string sortable searchable CS
source defaults to source.namestring searchable facetable RJT
source.homepage URL of the source's primary websitestring searchable RJT
source.id Id for source used by ReliefWeb integer searchable facetableSRJT
source.longname Official name of the source if different from source.namestring searchable facetable RJT
source.name  string searchable facetable RJT
source.shortname Short name of the source, typically an acronym e.g. UNICEFstring searchable facetable RJT
source.type defaults to source.type.namestring searchable facetable RJT
source.type.id Id for source type used by ReliefWeb integer searchable facetableSTRJT
source.type.name Values depend on content typestring searchable facetable RJT
status Values depend on content typestring searchable facetable RJTCDS
theme defaults to theme.namestring searchable facetable RJT
theme.id Id for theme used by ReliefWeb integer searchable facetableTRJT
theme.name Link for valuesstring searchable facetable RJT
title Titlestring sortable searchable RJT
type.code string sortable searchable facetable D
type.primary boolean  D
typedefaults to type.namestring searchable facetable JTDS
type.idId for entity type used by ReliefWeb integer searchable facetableTYJTDS
type.nameValues depend on content typestring searchable facetable JTDS
url Canonical urlstring  RJTCDS
vulnerable_groups defaults to vulnerable_groups.namestring searchable facetable R
vulnerable_groups
.id
Id for vulnerable group used by ReliefWeb integer searchable facetableVGR
vulnerable_groups
.name
Link for valuesstring searchable facetable R
NameDescriptionTypeSortable/ Searchable/ FacetableAdvanced search abbreviationPreset settings
body Main text in Markdown formatstringsearchable query: analysis latest
body-html Main text in HTML formatstring  
country Shortcut for country - defaults to country.namestring searchable facetable query: analysis latest
country.id Id for country used by ReliefWeb integer searchable facetableC 
country.iso3 ISO 3166-1 alpha-3 codestring searchable facetable  
country.name Name of country in Englishstring searchable facetable  
country.primary Flag to indicate this is the primary countryboolean   
country.shortname Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'string searchable facetable  
date Shortcut for date fields - defaults to date.createddate sortable facetable  
date.changed Date entry modified on ReliefWeb (ISO 8601)date sortable facetable  
date.created Date entry created on ReliefWeb (ISO 8601)date sortable facetableDAsort: latest
date.original Date entry first published by original source (ISO 8601)date sortable facetableDO 
disaster Shortcut for related disaster - defaults to disaster.namestring searchable facetable query: analysis latest
disaster.id Id for related disaster used by ReliefWeb integer searchable facetableD 
disaster.name Name assigned to the disaster based on the ReliefWeb disaster naming conventionstring searchable facetable  
disaster.glide Global IDEntifier number (GLIDE) of the disasterstring searchable facetable  
disaster_type Shortcut for disaster type - defaults to disaster_type.namestring searchable facetable query: analysis latest
disaster_type.id Id for disaster type used by ReliefWeb integer searchable facetableDT 
disaster_type.name Link for valuesstring searchable facetable  
disaster_type.code GLIDE hazard code for disaster type. Link for valuesstring searchable facetable  
feature defaults to feature.namestring searchable facetable  
feature.id Id for feature used by ReliefWeb integer searchable facetable  
feature.name Featured contentstring searchable facetable  
file File attachment shortcut - defaults to file.idinteger searchable  
file.copyright Copyright of file attachmentstring searchable  
file.description Description of file attachmentstring searchable  
file.filename File name of file attachmentstring   
file.id Id of file attachment used by ReliefWeb integer searchable  
file.mimetype MIME type of file attachmentstring   
file.preview Shortcut for preview image of file attachment - defaults to file.preview.urlstring   
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.url Link to file attachmentstring   
format Shortcut for content format - defaults to format.namestring searchable facetable  
format.id Id of content format used by ReliefWeb integer searchable facetableF 
format.name Link for valuesstring searchable facetable query: analysis latest
headline Shortcut for headline - defaults to headline.titlestring sortable searchable  
headline.featured  string sortable searchable facetable  
headline.image Shortcut for headline image - defaults to headline.image.idinteger searchable  
headline.image
.id
Unique id of headline image used by ReliefWeb integer searchable  
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 imagestring searchable  
headline.image
.copyright
Copyright attached to the headline imagestring searchable  
headline.image
.url
URL of the headline imagestring   
headline.summary Summary of body, if report is selected as headline. Typically 180-190 characters longstring searchable query: analysis latest
headline.title Headline text, if report is selected as headline. Typically 100-120 characters longstring sortable searchable query: analysis latest
id Unique id of report used by ReliefWeb integer sortable searchable  
image Image shortcut - defaults to image.idinteger searchable  
image.caption Caption attached to the imagestring searchable  
image.copyright Copyright attached to the imagestring searchable  
image.id Unique id of image used by ReliefWeb integer searchable  
image.mimetype MIME type of the imagestring   
image.filename File name of the imagestring   
image.url Link to the original imagestring   
image.url-large Link to a large image with a width of 680pxstring   
image.url-small Link to a small image with a width of 200pxstring   
image.url-thumb Link to a thumbnail image with a maximum width of 220px and a maximum height of 100pxstring   
language Shortcut for language - defaults to language.namestring searchable facetable query: analysis latest
language.code ISO 639-1 code of the language the entry is written instring searchable facetable  
language.id Id for language of report used by ReliefWeb integer facetableL 
language.name Language the report is written instring searchable facetable  
ocha_product Shortcut for OCHA product - defaults to ocha_product.namestring searchable facetable  
ocha_product.id Id of OCHA product used by ReliefWeb integer searchable facetable  
ocha_product.name Link for valuesstring searchable facetable  
origin Url of original report when it was added to ReliefWebstring   
primary_country Shortcut for primary country - defaults to primary_country.namestring searchable facetable query: analysis latest
primary_country
.id
Id of primary country used by ReliefWeb integer sortable searchable facetablePC 
primary_country
.name
Link for more informationstring sortable searchable facetable  
primary_country
.shortname
Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'string sortable searchable facetable  
primary_country
.iso3
ISO 3166-1 alpha-3 codestring sortable searchable facetable  
source Shortcut for sources - defaults to source.namestring searchable facetable query: analysis latest
source.id Id for source used by ReliefWeb integer searchable facetableS 
source.name Common name of sourcestring searchable facetable  
source.shortname Short name of the source, typically an acronym e.g. UNICEFstring searchable facetable  
source.longname Official name of the source if different from source.namestring searchable facetable  
source.homepage URL of the source's primary websitestring searchable  
source.type Shortcut for source type - defaults to source.type.namestring searchable facetable  
source.type.id Id for source type used by ReliefWeb integer searchable facetableST 
source.type.name Link for valuesstring searchable facetable  
status string searchable facetable query: analysis filter: analysis ['published', 'to-review'] latest ['published', 'to-review'] minimal ['published']
theme Shortcut for theme - defaults to theme.namestring searchable facetable  
theme.id Id of theme used by ReliefWeb integer searchable facetableT 
theme.name Link for valuesstring searchable facetable query: analysis latest
title Title of reportstring sortable searchable query: analysis latest minimal
url Canonical urlstring   
url_alias 'Friendly' url of the country string searchable  
vulnerable_groups Shortcut for vulnerable groups - defaults to vulnerable_groups.namestring searchable facetable query: analysis latest
vulnerable_groups
.id
Id for vulnerable groups used by ReliefWeb integer searchable facetableVG 
vulnerable_groups
.name
Link for valuesstring searchable facetable  
NameDescriptionTypeSortable/ Searchable/ FacetableAdvanced search abbreviationPreset settings
country Shortcut for country - defaults to country.namestring searchable facetable query: analysis latest
country.id Id for country used by ReliefWeb integer searchable facetableC 
country.iso3 ISO 3166-1 alpha-3 codestring searchable facetable  
country.primary Flag to indicate this is the primary countryboolean   
country.name Name of country in Englishstring searchable facetable  
country.shortname Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'string searchable facetable  
currentDeprecatedboolean sortable facetable  
date Shortcut for date - defaults to date.createddate sortable facetable  
date.created Date entry created on ReliefWeb (ISO 8601)date sortable facetableDAsort: latest
descriptionDescription of the disaster in Markdown formatstringsearchable query: analysis latest
description-htmlDescription of the disaster in HTML formatstring  
featuredFlag to indicate if the disaster is featured on ReliefWeb home pageboolean sortable facetable  
glideGlobal IDEntifier number (GLIDE) of the disasterstring sortable searchable query: analysis latest
id Unique id of disaster used by ReliefWeb integer sortable searchable  
name string sortable searchable query: analysis latest minimal
primary_country
.iso3
ISO 3166-1 alpha-3 codestring sortable searchable facetable  
primary_country Shortcut for primary country - defaults to primary_country.namestring searchable facetable  
primary_country
.id
Id of primary country used by ReliefWeb integer sortable searchable facetablePC 
primary_country
.iso3
ISO 3166-1 alpha-3 codestring sortable searchable facetable  
primary_country
.name
Link for more informationstring sortable searchable facetable  
primary_country
.shortname
Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'string sortable searchable facetable  
primary_typeShortcut for primary disaster type - defaults to primary_type.namestring searchable facetable  
primary_type.idId for primary disaster type used by ReliefWeb integer searchable facetableTY 
primary_type.nameName of primary disaster typestring searchable facetable  
related_glideRelated Global IDEntifier number (GLIDE)string searchable  
status 'current', 'alert',  'past'string searchable facetable query: analysis filter: analysis ['alert', 'alert-archive', 'archive', 'current', 'past'] latest ['alert', 'current', 'past'] minimal ['alert', 'current', 'past']
typeShortcut for disaster type - defaults to type.namestring searchable facetable query: analysis latest
type.codeCode of disaster typestring sortable searchable facetable  
type.idId of disaster type used by ReliefWeb integer searchable facetableTY 
type.nameLink for valuesstring searchable facetable  
type.primaryWhether disaster type is primary or notboolean   
url Canonical urlstring   
url_alias 'Friendly' url of the country string searchable  
NameDescriptionTypeSortable/ Searchable/ FacetableAdvanced search abbreviationPreset settings
currentDeprecatedboolean sortable 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 pageboolean sortable facetable  
id Unique id of country used by ReliefWeb integer sortable searchable sortlatest
iso3ISO 3166-1 alpha-3 codestring sortable searchable queryanalysis latest
nameCountry name in Englishstring sortable searchable queryanalysis latest minimal
shortnameShort name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'string sortable searchable queryanalysis latest
status Whether country has an active situationstring searchable facetable queryanalysis
url Canonical urlstring   
url_alias 'Friendly' url of the country string searchable  
video_playlist Playlist id of curated videos about the country string   
NameDescriptionTypeSortable/ Searchable/ FacetableAdvanced search abbreviationPreset settings
body Description of job in Markdown formatstringsearchable query: analysis latest
body-html Description of job in HTML formatstring  
career_categoriesShortcut for career categories - defaults to career_categories.namestring searchable facetable query: analysis latest
career_categories
.id
Id for career categories used by ReliefWeb integer searchable facetableCC 
career_categories
.name
Link for valuesstring searchable facetable  
cityShortcut for city - defaults to city.namestring searchable facetable  
city.idId of city used by ReliefWeb integer searchable facetable  
city.nameName of city in Englishstring searchable facetable  
country Shortcut for country - defaults to country.namestring searchable facetable query: analysis latest
country.id Id for country used by ReliefWeb integer searchable facetableC 
country.primary Flag to indicate this is the primary countryboolean   
country.name Name of country in Englishstring searchable facetable  
country.shortname Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'string searchable facetable  
country.iso3 ISO 3166-1 alpha-3 codestring searchable facetable  
date Shortcut for date - defaults to date.createddate sortable facetable  
date.changed Date entry modified on ReliefWeb (ISO 8601)date sortable facetable  
date.closingDate job closes to applicants (ISO 8601)datesortable facetableDC 
date.created Date entry created on ReliefWeb (ISO 8601)date sortable facetableDAsort: analysis
experienceShortcut for experience requirement - defaults to experience.namestring searchable facetable  
experience.idId for experience requirement used by ReliefWeb integer searchable facetableE 
experience.nameTime range of experience required for positionstring searchable facetable  
file Shortcut for file attachment - defaults to file.idinteger searchable  
file.description Description of the file attachmentstring searchable  
file.filename File name of the attachmentstring   
file.id Id for file attachment used by ReliefWeb integer searchable  
file.mimetype MIME type of the file attachmentstring   
file.url URL of the file attachmentstring   
how_to_applyApplication instructions for the job in Markdown formatstringsearchable query: analysis latest
how_to_apply-htmlApplication instructions for the job in HTML formatstring  
id Unique id of job used by ReliefWeb integer sortable searchable  
source Shortcut for source - defaults to source.namestring searchable facetable query: analysis latest
source.homepage URL of the source's primary websitestring searchable  
source.id Id for source used by ReliefWeb integer searchable facetableS 
source.longname Official name of the source if different from source.namestring searchable facetable  
source.name Common name of sourcestring searchable facetable  
source.shortname Short name of the source, typically an acronym e.g. UNICEFstring searchable facetable  
source.type Shortcut for source type - defaults to source.type.namestring searchable facetable  
source.type.id Id for source type used by ReliefWeb integer searchable facetableST 
source.type.name Link for valuesstring searchable facetable  
status Whether job is still currentstring searchable facetable query: analysis filter: analysis ['published', 'expired'] minimal ['published']
theme Shortcut for theme - defaults to theme.namestring searchable facetable query: analysis latest
theme.id Id for theme used by ReliefWeb integer searchable facetableT 
theme.name Link for valuesstring searchable facetable  
title Job titlestring sortable searchable query: analysis latest minimal
typeShortcut for type - defaults to type.namestring searchable facetable  
type.idId for job type used by ReliefWeb integer searchable facetableTY 
type.nameLink for valuesstring searchable facetable  
url Canonical urlstring   
url_alias 'Friendly' url of the country string searchable  
NameDescriptionTypeSortable/ Searchable/ FacetableAdvanced search abbreviationPreset settings
body Training description in Markdown formatstringsearchable query: analysis latest
body-html Training description in HTML formatstring  
career_categoriesShortcut for career categories - defaults to career_categories.namestring searchable facetable query: analysis latest
career_categories
.id
Id for career categories used by ReliefWeb integer searchable facetableCC 
career_categories
.name
Link for valuesstring searchable facetable  
cityShortcut for city - defaults to city.namestring searchable facetable  
city.idId of city used by ReliefWeb integer searchable facetable  
city.nameName of city in Englishstring searchable facetable  
costfree or fee-basedstring searchable facetable  
country Shortcut for country - defaults to country.namestring searchable facetable query: analysis latest
country.id Id for country used by ReliefWeb integer searchable facetableC 
country.iso3 ISO 3166-1 alpha-3 codestring searchable facetable  
country.name Name of country in Englishstring searchable facetable  
country.primary Flag to indicate this is the primary countryboolean   
country.shortname Short name of country where applicable, for example 'Syria' for 'Syrian Arab Republic'string searchable facetable  
dateShortcut for date - defaults to date.createddate facetable  
date.changedDate when the entry was last modified on ReliefWeb (ISO 8601)date sortable facetable  
date.createdDate when the entry was created on ReliefWeb (ISO 8601)date sortable facetable sort: 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 
file Shortcut for file attachment - defaults to file.idinteger searchable  
file.description Description of the file attachmentstring searchable  
file.filename File name of the attachmentstring   
file.id Id for file attachment used by ReliefWeb integer searchable  
file.mimetype MIME type of the file attachmentstring   
file.url URL of the file attachmentstring   
format Shortcut for training format - defaults to format.namestring searchable facetable query: analysis latest
format.id Id for training format used by ReliefWeb integer searchable facetableF 
format.name Whether training is on-site or onlinestring searchable facetable  
how_to_registerRegistration information in Markdown formatstringsearchable  
how_to_register
-html
Registration information in HTML formatstring  
id Unique id for training opportunity used by ReliefWeb integer sortable searchable  
language Shortcut for language - defaults to language.namestring searchable facetable  
language.code ISO 639-1 code of the language the entry is written instring searchable facetable  
language.id Id for language used by ReliefWeb integer facetableL 
language.name Language in which post is written (not necessarily language in which the training will be held)string searchable facetable  
source Shortcut for source - defaults to source.namestring searchable facetable query: analysis latest
source.id Id for source used by ReliefWeb integer searchable facetableS 
source.name Common name of sourcestring searchable facetable  
source.longname Official name of the source if different from source.namestring searchable facetable  
source.homepage URL of the source's primary websitestring searchable  
source.shortname Short name of the source, typically an acronym e.g. UNICEFstring searchable facetable  
source.type Shortcut for source type - defaults to source.type.namestring searchable facetable  
source.type.id Id for source type used by ReliefWeb integer searchable facetableST 
source.type.name Link for valuesstring searchable facetable  
status Whether training is still currentstring searchable facetable query: analysis filter: analysis ['published', 'expired'] latest ['published'] minimal ['published']
theme Shortcut for theme - defaults to theme.namestring searchable facetable query: analysis latest
theme.id Id for theme used by ReliefWeb integer searchable facetableT 
theme.name Link for valuesstring searchable facetable  
title Title of coursestring sortable searchable query: analysis latest minimal
typeShortcut for type - defaults to type.namestring searchable facetable  
type.idId for training type used by ReliefWeb integer searchable facetableTY 
type.nameLink for valuesstring searchable facetable  
url Canonical urlstring   
url_alias 'Friendly' url of the country string searchable  
NameDescriptionTypeSortable/ Searchable/ FacetableAdvanced search abbreviationPreset settings
content_typeContent types published from this sourcestring sortable searchable  
country Shortcut for country - defaults to country.namestring searchable facetable  
country.id Id for country used by ReliefWeb integer searchable facetableC 
country.iso3 ISO 3166-1 alpha-3 codestring searchable facetable  
country.name Name of the country in English where the source headquarters is locatedstring searchable facetable  
country.primary Flag to indicate this is the primary countryboolean   
country.shortname Short name of the country in English where the source headquarters is locatedstring searchable facetable  
descriptionDescription of the source in Markdown formatstringsearchable  
description-htmlDescription of the source in HTML formatstring  
fts_idId number for organization used by FTSnumber sortable searchable  
homepageUrl of organizationstring searchable  
id Unique id for source used by ReliefWeb integer sortable searchable sort: latest
logo Shortcut for logo - defaults to logo.url string  
logo.filename File name of the logostring   
logo.filesize File size of the logostring   
logo.height Height of the logo integer   
logo.id Id for logo used by ReliefWeb integer   
logo.mimetype MIME type of the logostring   
logo.url URL of the logostring   
logo.width Width of the logo integer   
longnameOfficial name of source, where applicablestring sortable searchable query: analysis latest
nameName of sourcestring sortable searchable query: analysis latest minimal
shortnameName of the source in abbreviated format, where applicablestring sortable searchable query: analysis latest
status Whether source is active or notstring searchable facetable query: analysis filter: analysis ['active', 'inactive'] latest ['active', 'inactive'] minimal ['active', 'inactive']
typeShortcut for type of organization - defaults to type.namestring searchable facetable  
type.idId of organization type used by ReliefWeb integer searchable facetableTY 
type.nameLink for valuesstring searchable facetable  
url Canonical urlstring   
url_alias 'Friendly' url of the country string searchable