ReliefWeb Publishing API

ReliefWeb has long had an API to help distribute its content, open to anyone. Now there is also a way for organizations to provide content through the API too.

Content will only be accepted from organizations who already have reports, jobs or trainings published on ReliefWeb. They will be identified via secret API keys and information will only be fetched from pre-defined urls.

You will need to contact ReliefWeb to get set up correctly. After setting up and testing, your organization can submit information automatically to be processed by ReliefWeb editors.

When we provide your API provider ID and key we will include a complete and detailed guide to submitting content through the API, with examples.

This is a short guide to the one-time setup, and what happens next.

Getting set up

Eligible organizations

All organizations listed on the organizations page are invited to use the Publishing API.

Trusted sources

To make sure all the content can be trusted, the API fetches all text, images and files from urls controlled by the organization. For example: https://your.domain/reports, https://your.domain/files, https://your.domain/images.

API key and provider ID

The first step is to contact us with the name of your organization and your trusted urls. When approved and verified, we will issue an API key and provider ID. This provides another level of security and trust.

Universally Unique Identifiers (UUIDs)

The Publishing API uses version 5 universally unique identifiers (see https://en.wikipedia.org/wiki/Universally_unique_identifier for background).

Each submission has a unique identifier which is UUID v5 generated from the url of the content to submit, on your site, and the namespace "8e27a998-c362-5d1f-b152-d474e1d36af2".

For more details and ways to create a UUID, see the Appendix.

Taxonomies

ReliefWeb uses tags to help visitors find the content they need. Some of these tags are mandatory. Before publishing content, organizations should consider matching their own ways of tagging information with that used by ReliefWeb. See Content Specifications. Values are listed in the ReliefWeb Humanitarian Terms page or through the API, including the references list.

Do ask for help with this if anything is not clear.

Most tags don’t change over time, but the list of disasters is constantly being updated. Those can be looked up on the ReliefWeb site or through the API by Glide number or by name.

For example, reports require information about the country, the language it's published in, and the format. Jobs require the job type, career category and a range of years of experience. Values are listed in the ReliefWeb Humanitarian Terms page or through the API references list.

Disaster names, where new ones are added over time, can be looked up through the API by Glide number of by name.

Publishing content

Workflow

These instructions assume an organization is verified, has an API key and Provider ID, is familiar with the UUIDs and has matched their tags with those on ReliefWeb (see previous section).

Requests use the http PUT method.

For now, the endpoint is https://test.api-reliefweb-int.ahconu.org. This will change when the API goes live.

Content is submitted as specified - see following sections for Reports, Jobs and Training.

Successful content submission will return an HTTP 202 (Accepted) code with a message such as "Document queued for processing."

Content is then queued for review by the editorial team.

Feedback on the review will be communicated to an email address or webhook if your organization has supplied those. Email addresses for notification can also be included in each submission.

After review, valid and relevant documents are available through the site and the API.

Use the UUID ({uuid} in this example) to find the content: https://test.api-reliefweb-int.ahconu.org/v2/reports/{uuid}?appname=your-domain

Content specifications

The schemas listed below are the canonical place for information about which fields are available, which are required, and what they can and cannot contain. For reference for the patterns allowed in string fields, see this table

• Reports

  Details, including field descriptions and which ones are required, are here: https://test.reliefweb-int.ahconu.org/post-api-schemas/v2/report.json.

  Mandatory fields:
  • url
  • uuid
  • title
  • source
  • country
  • format
  • language
  • published
  • body

• Jobs

  Details, including field descriptions and which ones are required, are here: https://test.reliefweb-int.ahconu.org/post-api-schemas/v2/job.json.

  For general guidelines, see this blogpost.

  Mandatory fields:
  • url
  • uuid
  • title
  • source
  • closing_date
  • body
  • how_to_apply
  • job_type
  • job_experience
  • career_category

• Training

  Details, including field descriptions and which ones are required, are here: https://test.reliefweb-int.ahconu.org/post-api-schemas/v2/training.json.

  Mandatory fields:
  • url
  • uuid
  • title
  • source
  • format
  • event_url
  • cost
  • category
  • training_language
  • language
  • body
  • how_to_register

Updating content

To update previously submitted content, use the same UUID to send the updated data via a PUT request.

Changed information will replace what has been submitted previously.

To replace an image or an attachment, use the same URL with an updated checksum.

Unpublishing content

Currently you will need to contact the ReliefWeb editorial team to request a document to be unpublished.

Quotas and rate limit

A provider can submit up to 50 documents a day as fast as 1 document per minute. Requests exceeding this rate will receive an HTTP error response code.

Please note that processing documents can take some time.

Appendix

Creating a UUID

To create a UUID, use the RW Publishing API namespace - 8e27a998-c362-5d1f-b152-d474e1d36af2 - and the url of the content.

Many different tools exist, including a cli tool uuidgen, an online tool uuidtools, a PHP library Symfony UID, and a npm library uuid. The url of the content must use one of the trusted urls (see Trusted sources) and must be unique for that content.

For example, to create a uuid for a unocha report with uuidgen:

uuidgen --sha1 --namespace 8e27a998-c362-5d1f-b152-d474e1d36af2 --name “https://www.unocha.org/news/todays-top-news-occupied-palestinian-territory-lebanon-cuba”

Which gives: d5eed32f-f495-5e48-abdb-57dedaf2eedd