FEWS NET API

The FEWS NET Data Warehouse (FDW) has a comprehensive REST API that can be used to access data stored in the data warehouse, according to the user’s permissions. The API allows for greater flexibility than the FEWS NET Data Explorer (FDE).

The FDW REST API has a wide range of functionality. Comprehensive, interactive API documentation is available here: https://fdw.fews.net/en/docs/rapidoc/.

Authentication

The FDW REST API supports authentication using a range of methods, including:

Session Authentication using a POST request containing username and password to /accounts/login/ and receiving and storing a session cookie that can be presented with subsequent requests
Token Authentication using a POST request containing username and password to /api-token-auth/ and receiving and storing a response like {"token": "abcdefgh..."} that can be presented in subsequent requests by including an HTTP header in the form Authorization: JWT <token> . Alternatively the token can be presented as a query parameter in the URL, for example, ?jwt=<token>

Requests without any authentication may succeed but will only return public data.

If using refreshable links in Excel, you will be prompted to enter your FDW login credentials. Staff will not be able to use single sign-on credentials. If you do not have an FDW-specific password, you will need to request one. Select the Basic option, enter your User name and Password, then click Connect.

Endpoints

There are a number of REST API endpoints for accessing time series data for different domains. Each domain has separate endpoints that return the list of data series for that domain. These endpoints support the same filters as the main time series endpoints and it should not be necessary to use them if the requirement is only to extract time series data matching a particular criteria.

Domain	Endpoint to access time series data	Endpoint to access a list of data series
Market Prices	https://fdw.fews.net/api/marketpricefacts/	https://fdw.fews.net/api/marketproduct/
Cross Border Trade	https://fdw.fews.net/api/tradeflowquantityvalue/	https://fdw.fews.net/api/tradeflowquantity/
Food Security Classifications	https://fdw.fews.net/api/ipcphase/	https://fdw.fews.net/api/ipcclassification/
Food Insecure Population Estimates	https://fdw.fews.net/api/ipcpopulationsize/	https://fdw.fews.net/api/ipcpopulation/

There are also separate endpoints for extracting Geographic Units, including Livelihood Zones, Administrative Boundaries and Food Security Classification areas of analysis:

Tabular representations of geographic units: https://fdw.fews.net/api/geographicunit/
Spatial representations of geographic units: https://fdw.fews.net/api/feature/

Extract formats

All endpoints support a standard range of extract formats, which can be accessed using an extension on the URL (for example, https://fdw.fews.net/api/marketpricefacts.csv) or a query parameter (for example, https://fdw.fews.net/api/marketpricefacts/?format=json).

The standard values for the format parameter include:

html : a plain HTML table
json : a JavaScript Object Notation text string
csv : a UTF-8 comma-separated values file with a header row and a UTF-8 byte order mark (BOM) to enable Microsoft Excel and other tools to recognize the file correctly
xml : an extensible markup language text string. XML is the recommended format for importing data into Microsoft Excel.

Some, but not all, endpoints also support spatial extract using the geojson or kml extract formats. Note that when doing spatial extracts for time series data the extract sizes can become extremely large. It is frequently better to do two separate extracts: one to fetch the time series data in a tabular format such as csv and a second to fetch the associated geographic units using the https://fdw.fews.net/api/feature/ endpoint and then joining them in the selected analytic tool.

Filters and pagination

Many of the time series data domains contain a large amount of data, such that attempting to extract all of it in a single request may fail due to browser timeouts. Best practice is to filter the request to include only the data that is required, or to use pagination to limit the size of each response.

Common time series filters

The following filters can be used with all time series data. Typically a request contains a country_code or country filter and frequently a start_date filter as well.

Geography
- country_code : the ISO 3166-1 alpha-2 two letter code for a country.
  Example: to fetch price data for Kenya and Ethiopia one could use https://fdw.fews.net/api/marketpricefacts.csv?country_code=KE&country_code=ET
- country : similar to the country_code filter above, but uses the name of the country rather than the ISO code. This is easier to use, but may be slower, especially for large extracts.
  Example: https://fdw.fews.net/api/marketpricefacts.csv?country=Kenya
Data sources
- dataseries : the internal id for a Data Series can be used to return the full set of data for a single Data Series. The id can be determined from the FDW or FDE.
  Example: https://fdw.fews.net/api/marketpricefacts.csv?dataseries=1577
- datasourcedocument : the internal id for a Data Source Document, can be used to return the full set of data for a single Document. The id can be determined from the FDW or FDE.
  Example: https://fdw.fews.net/api/marketpricefacts.csv?datasourcedocument=4304
Dates
- as_of_date : records that were current at a given date, specified in YYYY-MM-DD format.
  Example: https://fdw.fews.net/api/marketpricefacts.csv?as_of_date=2021-07-31
- start_date : records current on or after a given date, specified in YYYY-MM-DD format.
  Example: https://fdw.fews.net/api/marketpricefacts.csv?start_date=2021-08-01
- end_date : records current on or before a given date, specified in YYYY-MM-DD format.
  Example: https://fdw.fews.net/api/marketpricefacts.csv?end_date=2021-08-31
- collection_date : records collected on a given date, specified in YYYY-MM-DD format. For most time series the start_date and end_date are a better way to find the correct data. However, for forecasts and projections, such as the Food Security Classification data, there may be multiple data points for a single time period. For example there may be a medium term forecast made 6 months ago, a near term forecast made 3 months ago and a current forecast made this month. In these situations it is common to want to find the data for the current forecast only.
  Example: https://fdw.fews.net/api/ipcphase.csv?collection_date=2021-08-01

Domain specific filters

Each domain also supports specific filters to allow the selection of data based on key metadata fields.

Price domain

cpcv2 : records under a given CPC v2 code. CPC is the UN’s Central Product Classification. CPC is a hierarchy, so specifying L02122AF will return only those matching records, whereas filtering for L02122 would return prices for both L02122AA and L02122AF.
Example: https://fdw.fews.net/api/marketpricefacts.csv?cpcv2=L02122
product : records matching a given product name or description. This is easier to use, but may be slower and less accurate than filtering using the cpcv2 .
Example: https://fdw.fews.net/api/marketpricefacts.csv?product=maize
price_type : records with a given price type, specified as Assembly, Retail, Wholesale, Producer, Export, Spot or Wage.
Example: https://fdw.fews.net/api/marketpricefacts.csv?product=maize&price_type=Wholesale
product_source : records with a given product source, specified as Local, Import or Export.
Example: https://fdw.fews.net/api/marketpricefacts.csv?product=rice&product_source=Import
market : the internal id for a Market, can be used to return the full set of data for a single Market,
Example: https://fdw.fews.net/api/marketpricefacts.csv?market=57824

Trade domain

source : records for trade flows originating from a specific country, specified by name or ISO 3166-1 alpha-2 code. Using the standard country_code or country filters will find all records where that country is involved as either the source country, the destination country or the reporting country.
Example: https://fdw.fews.net/api/tradeflowquantityvalue.csv?source=Kenya
destination : records for trade flows terminating in a specific country, specified by name or ISO 3166-1 alpha-2 code. Using the standard country_code or country filters will find all records where that country is involved as either the source country, the destination country or the reporting country.
Example: https://fdw.fews.net/api/tradeflowquantityvalue.csv?destination=ET
cpcv2 : records under a given CPC v2 code. CPC is the UN’s Central Product Classification. CPC is a hierarchy, so specifying R01122AB will return only those matching records, whereas filtering for R01122 would return trade flow quantities for both R01122AB and R01122AC.
Example: https://fdw.fews.net/api/tradeflowquantityvalue.csv?cpcv2=R01122
product : records matching a given product name or description. This is easier to use, but may be slower and less accurate than filtering using the cpcv2 .
Example: https://fdw.fews.net/api/tradeflowquantityvalue.csv?product=maize
trade_type : records with a given trade type, specified as Formal or Informal.
Example: https://fdw.fews.net/api/tradeflowquantityvalue.csv?product=maize&trade_type=Informal

IPC FIC domain

scenario : records for a specific scenario only, specified as CS, ML1 or ML2 where CS is the Current Situation, ML1 is the Near Term projection for up to three months and ML2 is the Medium Term projection for 4 to 6 months.
Example: https://fdw.fews.net/api/ipcphase.csv?scenario=ML1

IPC FIPE domain

scenario : records for a specific scenario only, specified as CS OR FIPE6 where CS is the Current Situation and FIPE6 is the Medium Term projection for four to six months.
Example: https://fdw.fews.net/api/ipcpopulationsize.csv?scenario=CS
phase : records for the population in specific Phases only, specified as 2 or 3+.
Example: https://fdw.fews.net/api/ipcpopulationsize.csv?phase=3+

Spatial domain

unit_type : records for a specific unit type only, such as admin1 or fsc_admin_lhz. Typical unit types include:
- admin1: First level administrative boundaries
- admin2 : Second level administrative boundaries
- fsc_admin: Food Security Classification unit of analysis based on an Administrative Unit
- fsc_admin_lhz: Food Security Classification unit of analysis based on the intersection of an Administrative Unit and a Livelihood Zone
- Idp_camp: Point location for internally displaced persons
- livelihood_zone: Livelihood zone
- market: Point location for market price data

Example: https://fdw.fews.net/api/geographicunit.csv?country_code=KE&unit_type=admin1.

as_of_date : records that were current at a given date, specified in YYYY-MM-DD format.
Example: https://fdw.fews.net/api/feature.geojson?country_code=ET&as_of_date=2021-07-31
data_type : records for a specific data type only. The only frequently used value is ?data_type=official which is used to limit the response to records in the current official admin boundary set.

When using JSON-formatted responses, the data can be paginated by passing page_size and offset parameters as part of the request.

For example a request for https://fdw.fews.net/api/ipcphase.json?start_date=2021-06-01&scenario=ML1&country_code=ET&page_size=10&offset=0 will return the following response:

CODE

{
"count": 1040,
"next": "https://fdw.fews.net/api/ipcphase.json?country_code=ET&offset=10&page_size=10&scenario=ML1&start_date=2021-06-01",
"previous": null,
"results": [
    <snip>
]
}

Field Selection

By default the API responses will contain a large number of fields. For some domains they may include various additional statistics such as the value one year ago or the five-year average. It is possible to control which fields are returned by the API using the fields parameter.

A reduced set of the commonly used fields can be selected using ?fields=simple.

Alternatively, specific fields can be specified in a comma-separated list such as ?fields=dataseries,start_date,period_date,value,two_year_average .

Geographic Units

Spatial and tabular extracts of geographic units support some additional sets of fields:

with_population : includes an estimate of total males, total females, total population, area, and population density in the extract.
Example: https://fdw.fews.net/api/geographicunit.csv?unit_type=admin1&as_of_date=2021-08-01&fields=with_population
with_demography : includes an estimate of total males and females in each age bracket in addition to the fields provided by with_population.
Example: https://fdw.fews.net/api/geographicunit.csv?unit_type=admin1&as_of_date=2021-08-01&fields=with_demography
with_attributes : includes additional attributes that were part of the original shapefile database and may not be mapped onto other FDW fields.
Example: https://fdw.fews.net/api/geographicunit.csv?unit_type=lhz&as_of_date=2021-08-01&fields=with_attributes

Population estimates are derived from the LandScan data set. Demographic breakdowns are derived from the WorldPop data set.

Metadata Definitions

To access metadata definitions and details corresponding to a data extract, add the word metadata to your API call link between the endpoint and parameters. This information can be accessed in html, PDF, or JSON formats.

Example

If your API call is:

https://fdw.fews.net/api/marketpricefacts/?dataseries=2567202&format=html

You can call metadata definitions using:

https://fdw.fews.net/api/marketpricefacts/metadata/?dataseries=2567202&format=html

Temporal Aggregation

By default, the REST API endpoints return a monthly value. For data collected on a monthly schedule, the data will be represented as data for each month. Data collected on a less frequent basis, such as quarterly or ad hoc data, will be returned for the dates it is valid for, with gaps in the intervening months. Data that is collected more frequently, such as weekly data, will be aggregated to a monthly value using an appropriate function.

The level of temporal aggregation can be controlled by passing the schedule parameter in the request.

Example

?schedule=Quarterly will force aggregation to a quarterly schedule.

?schedule=Daily will return all data in its raw form without any aggregation.

Examples

Extract all market price data for Ethiopia, with common fields only, in csv format: https://fdw.fews.net/api/marketpricefacts.csv?country_code=ET&fields=simple

Extract all market price data for Ethiopia for July 2021 with the original collection frequency, in csv format: https://fdw.fews.net/api/marketpricefacts.csv?country_code=ET&start_date=2021-07-01&end_date=2021-07-31&schedule=Daily

Extract all cross border trade data for imports to Mozambique for July 2021, in csv format: https://fdw.fews.net/api/tradeflowquantityvalue.csv?country_code=MZ&start_date=2021-07-01&end_date=2021-07-31

Extract the global near term FEWS NET Food Security Classifications made in July 2021, in GeoJSON format: https://fdw.fews.net/api/ipcphase.geojson?collection_date=2021-07-01&scenario=ML1

Extract the global medium term FEWS NET Food Insecure Population Estimates for people in Phase 3 or above, in CSV format: https://fdw.fews.net/api/ipcpopulationsize.csv?phase=3+

Extract the current Admin2 boundaries for Kenya, with additional demographic data, in GeoJSON format: https://fdw.fews.net/api/feature.geojson?country_code=KE&unit_type=admin2&as_of_date=2021-07-31&fields=with_demography&data_type=official

Extract the current Food Security Classification boundaries for Ethiopia, in GeoJSON format: https://fdw.fews.net/api/feature.geojson?country_code=ET&unit_type=fsc_admin&unit_type=fsc_admin_lhz&as_of_date=2021-07-31

Extract the current Livelihood Zone boundaries for Ethiopia, in GeoJSON format: https://fdw.fews.net/api/feature.geojson?country_code=ET&unit_type=livelihood_zone&as_of_date=2021-07-31

Additional Documentation

The FDW REST API has a wide range of functionality. Comprehensive, interactive API documentation is available: https://fdw.fews.net/en/docs/rapidoc/.

Support

If your use case is not covered by our documentation, please contact Helpdesk Support.