Migration Data Portal – API Documentation
Purpose
The Global Migration Data Portal's database includes data on human mobility, forced migration and displacement, labour migration, remittances as well as socioeconomic context indicators relevant to migration. The database has international data from UN agencies, academia and think tanks as well as national data from pilot countries. The Portal API provides access to the international data in its database, covering various indicators at the global, regional, subregional and national levels. It allows data specialists and developers to query the Portal database, giving users the ability to analyze and visualize the data according to their specific needs.
Parameters
When a user hits the Portal’s API endpoint, it will only return the first set of 1,000 observations. To fetch the next 1,000 records, the user needs to request the next page. It should be noted that the API’s pagination number starts from 0.
| Name |
Type |
Description |
| page |
Integer [optional] |
In the API response, we have added the number of observations along with the total records and the number of pages. To request data from a specific page, use the page parameter. |
| year |
Integer [optional] |
The year parameter allows you to retrieve data for a specific year. To use this filter, set the year parameter to the desired year in the format 'YYYY' (e.g., 2020, 2021). The API will return results that correspond to the specified year.
|
| indicator |
String [mandatory] |
To filter data for a specific indicator, you must use the indicator code as a mandatory parameter in your API request. Each request must specify at least one indicator, appending the string 'default' to it. For detailed information on available indicators and their corresponding codes, please refer to the Portal’s Data Catalogue.
To query multiple indicators, format your request as follows: indicator=refug_host+asyl_origin.
To query a single indicator, the request should be formatted as follows: indicator=refug_host+default.
Note that when filtering for a single indicator, including the 'default' parameter is also required.
|
| country |
Integer [optional] |
Filter data by one or more countries using the country parameter, which accepts the UNSD country and area codes (M49) for countries. The API returns results that correspond to the specified countries and their related indicators.
To query multiple countries simultaneously, separate the M49 codes with a '+' operator. For example, country=4+454 filters data for Afghanistan and Malawi, where '4' and '454' are their respective M49 codes. |
| unsd_region |
Integer [optional] |
Filter data by one or more UNSD Regions using the unsd_region parameter, which accepts the UNSD country and area codes (M49) for regions. The API returns results that correspond to the specified UNSD Region and their related indicators.
To query multiple regions simultaneously, separate the M49 codes with a '+' operator. For example, unsd_region=2+19 filters data for Africa and America, where '2' and 19' are their respective M49 codes. |
| unsd_subregion |
Integer [optional] |
Filter data by one or more UNSD Sub-regions using the unsd_subregion parameter, which accepts the UNSD country and area codes (M49) for sub-regions. The API returns results that correspond to the specified UNSD Sub-region and their related indicators.
To query multiple sub-regions simultaneously, separate the M49 codes with a '+' operator. For example, unsd_subregion=14+21 filters data for Eastern Africa and Northern America, where '14' and 21' are their respective M49 codes.
Note: In the API response, the sub-regions for 'Sub-Saharan Africa' and 'Latin America and the Caribbean' are replaced with their intermediate region groupings. Therefore, instead of 'Sub-Saharan Africa', the API response includes data for 'Eastern Africa', 'Middle Africa', 'Southern Africa', and 'Western Africa'. Similarly, 'Latin America and the Caribbean' are detailed as 'Caribbean', 'Central America', and 'South America'. Consequently, the corresponding M49 codes for these areas reflect the Intermediate Region Codes as defined by the UNSD.
|
| global |
boolean [optional] |
When set global=true, the request will result in global aggregates for the specified indicators. |
Note: The geographic reference area parameters (country, region, subregion, global) are mutually exclusive. This means that you can only select one of these parameters for each individual API request. Incorporating multiple geographic reference areas in a single request is not supported due to the design and structure of the Migration Data Portal's processing system.
Request
The Portal API uses the standard HTTP GET method for data retrieval and provides JSON-encoded responses, accompanied by standard HTTP response codes.
Method: GET
Base URL: https://www.migrationdataportal.org/api/international-values?indicator=default
Response
In general, querying the API provides the user with the following results in two JSON objects:
- pagination:
- current_page: Indicates the current page number of the response. The default starting page number is 0.
- total_pages: Represents the total number of pages into which the response is divided if the total observations exceed the page size limit. This parameter indicates how many pages the user's request spans.
- total_observations: Shows the total number of observations resulting from the user's requests.
- observations_per_page: Specifies the maximum number of observations included on each page. The default limit is set at 1,000 observations and this value is fixed, meaning it cannot be altered by the user.
- observations:
- REF_AREA (INT): Represents the geographic area code using the United Nations Statistics Division's (UNSD) M49 coding system. This system classifies locations into four levels: countries, subregions, regions, and a global scale. Within the Migration Data Portal database, the term "Subregion" specifically refers to the "Intermediate Region Code" in the UNSD M49 country code list.
- REF_AREA_DESC (String): Provides the full name of the geographic area and description of the geographic area code.
- REF_AREA_TYPE (String): Indicates the type of geographic area. Valid values include “World", "UN SD Region", "UN SD Subregion", "IOM Region", and "Country". this classification aids in filtering and analysis at different geographical levels.
- INDICATOR (String): Contains the code for the indicator used to filter the API request. For detailed list of indicators and indicator codes please see the Portal’s Data Catalogue.
- INDICATOR_DESC (String): Offers descriptive titles of the indicators, which explain the data aspect being measured.
- UNIT_MEASURE (String): Specifies the unit of measurement for the data, such as “percent (%)”, “categorical”, “country”.
- TIME_PERIOD (Integer): Indicates the reference year of the data.
- OBS_VALUE (Float): The observed value for the selected parameters.
- IND_FOOTNOTE (String): Includes additional footnotes and disclaimers related to the indicator.
- DATA_SOURCE (String): Identifies the origin of the data and the date of publication.
- DATA_SOURCE_LINK (String): Provides a URL linking directly to the original data source.
Access and Authentication
To ensure secure access to the Migration Data Portal’s API, an API key is required for each request to authenticate the user. The API key acts as a unique identifier and a secret token that the server uses to validate the request's origin and permissions. This key should be treated as sensitive information and is not to be shared publicly or with unauthorized parties.
Obtaining an API Key
Please use this form to register for an API key. Upon completing the registration form the Migration Data Poral team will review your credentials and share your unique API key.
Including the API Key in Requests
To authenticate the API request to Migration Data Portal, include your API key in the request header. The header should use the format api-key: <API_KEY_HERE>. This ensures that your key is securely transmitted.
Usage and Examples
