Migration Data Portal – API Documentation

Purpose

This page provides a detailed description of the Migration Data Portal's API and its endpoints. The Global Migration Data Portal Database includes data on human mobility, forced migration and displacement, labour migration, remittances as well as socioeconomic context indicators relevant to migration. The Portal 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. The Portal API 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., 2023, 2024). The API will return results that correspond to the specified year.

You can request for multiple years by concatenating the different years using “+” operator (e.g. 2023+2024).
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). 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?

Response

In general, querying the API provides the user with the following results in two JSON objects:

  1. 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.
  2. 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 SDK Samples

# The sample Python script below sends a request to the Migration Data Portal API to retrieve data for ‘stock_abs_’ and 'refug_host' indicators in 2015 and 2020. It will raise an exception if the request is unsuccessful. Otherwise, it parses the JSON response from the API.

# importing necessary libraries.

import requests

# Setting up the API URL.

base_url = 'https://www.migrationdataportal.org/api/international-values?'

# Setting up the request header with API key.

header_ = {'api-key': '3827056fe2ed0c23fc3a643336e30000'}

# Defining the parameters for the GET request.

params_ = {

     # Specifying the indicators.

    'indicator': 'stock_abs_+refug_host',

    # Specifying the years for which data is requested.

    'year': '2015+2020'}

# Handling exceptions and errors.

try:

    # Making a GET request with the specified header and parameters.

    api_response = requests.get(base_url, headers=header_, params=params_)

    # Raise an exception if the request returned an unsuccessful status code (e.g., 400, 401, 404, etc.).

    api_response.raise_for_status()

    # Parsing the JSON response if the request was successful.

    response_json = api_response.json()

except Exception as e:

    # Catch any Exception and print it.

    print("An error occurred:", e)

# The sample R script below sends a request to the Migration Data Portal API to retrieve data for ‘stock_abs_’ and 'refug_host' indicators in 2015 and 2020. It will raise an exception if the request is unsuccessful. Otherwise, it parses the JSON response from the API.

# Loading necessary libraries

library(httr)

library(jsonlite)

# Setting up the API URL

base_url <- 'https://www.migrationdataportal.org/api/international-values?'

# Setting up the request header with API key

headers_ <- add_headers(`api-key` = '3827056fe2ed0c23fc3a643336e30000')

# Defining the parameters for the GET request

params_ <- list(

  indicator = 'stock_abs_+refug_host',

  year = '2015+2020'

)

# Handling exceptions and errors using tryCatch

response_json <- tryCatch({

  # Making a GET request with the specified header and parameters

  api_response <- GET(base_url, headers_, query = params_)

  # Check if the request was successful (status code 200)

  if (status_code(api_response) != 200) {

    stop("Failed to fetch data: ", status_code(api_response))

  } 

  # Parsing the JSON response

  content(api_response, as = "parsed", type = "application/json") 

}, error = function(e) {

  # Catch and print any errors

  message("An error occurred: ", e)

  NULL

})

# Print the JSON response if successful

if (!is.null(response_json)) {

  print(response_json)

}

The sample PHP script below sends a request to the Migration Data Portal API to retrieve data for ‘stock_abs_’ and 'refug_host' indicators.

<?php

$curl=curl_init();

curl_setopt_array($curl, array(

  CURLOPT_URL => 'https://www.migrationdataportal.org/api/international-values?indicator=stock_abs_+refug_host',

  CURLOPT_RETURNTRANSFER => true,

  CURLOPT_ENCODING => '',

  CURLOPT_MAXREDIRS => 10,

  CURLOPT_TIMEOUT => 0,

  CURLOPT_FOLLOWLOCATION => true,

  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

  CURLOPT_CUSTOMREQUEST => 'GET',

  CURLOPT_HTTPHEADER => array(

    'api-key: 3827056fe2ed0c23fc3a643336e30000',

    'Authorization: Basic aW9taW50OmlvbWludA=='

  ),

));

$response = curl_exec($curl);

curl_close($curl);

echo $response;

The sample JavaScript program below sends a request to the Migration Data Portal API to retrieve data for ‘stock_abs_’ and 'refug_host' indicators in 2015 and 2020.

// Function to fetch data from the API

async function fetchMigrationData() {

    // API URL

    const baseUrl = 'https://www.migrationdataportal.org/api/international-values?indicator=default';

    // API key header

    const headers = {

        'api-key': '3827056fe2ed0c23fc3a643336e30000'

    };   

    // Parameters to be appended to the URL

    const params = new URLSearchParams({

        indicator: 'default+stock_abs_+refug_host',

        year: '2015+2020'

    });

    // Full URL with query parameters

    const url = `${baseUrl}&${params.toString()}`;   

    try {

        // Making the GET request

        const response = await fetch(url, {

            method: 'GET',

            headers: headers

        });       

        // Check if the response was successful

        if (!response.ok) {

            throw new Error(`HTTP error! Status: ${response.status}`);

        }       

        // Parsing the JSON response

        const data = await response.json();       

        // Log the response

        console.log(data);       

    } catch (error) {

        // Handle any errors

        console.error("An error occurred:", error);

    }

}

// Call the function

fetchMigrationData();