Endpoints, Lists and Items

This page documents the endpoints for requests and explains the differences between list and item requests.

Endpoints

There are nine types of content available through the API, each with a dedicated endpoint. reports, disasters, countries, jobs, training, sources, blog, book 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.
  • blog - Blog posts about ideas and projects to grow and improve ReliefWeb.
  • book - 'Static' information about the site and humanitarian resources. Besides the help pages and terms and conditions, there are pages on location maps, taxonomy descriptions and how to share humanitarian content on ReliefWeb.
  • references - Our taxonomy. ReliefWeb's editorial team tag content with to make it easier to organize and find specific content. These are detailed here to make so they can be more transparently matched with vocabularies used by other organizations.

Lists and items

There are two main types of request list and item:

  • List requests - without a content id.

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

    Note: all parameters can be used with list requests.

    Examples:

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

      GET:

      https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME

      POST:

      https://api.reliefweb.int/v1/reports?appname=REPLACE-WITH-A-DOMAIN-OR-APP-NAME
      {
}

  • 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=REPLACE-WITH-A-DOMAIN-OR-APP-NAME&fields[include][]=source.name

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