API Reference

This page contains the complete API reference for the dtmapi package.

DTMApi Class

class dtmapi.DTMApi(subscription_key: str | None = None, api_version: str = 'v3', timeout: int | None = None, max_retries: int | None = None, retry_delay: float | None = None)[source]

Bases: object

Python interface to DTM API endpoints. Supports both v2 (legacy) and v3 (current). Requires Ocp-Apim-Subscription-Key for authentication.

API Version Differences:

Feature

v2

v3

IDP Admin 0, 1, 2 Data

Yes

Yes

Country List

Yes

Yes

Operation List

Yes

Yes

Gender/Sex Disaggregation

No

Yes

Origin of Displacement

No

Yes

Displacement Reason

No

Yes

Status

Legacy

Current

Usage Examples:

v3 API (default - recommended for new projects):

api = DTMApi(subscription_key="YOUR-KEY")
data = api.get_idp_admin0_data(CountryName="Sudan")
# Returns IDP data WITH gender, origin, and reason fields

v2 API (legacy - for historical data compatibility):

api = DTMApi(subscription_key="YOUR-KEY", api_version="v2")
data = api.get_idp_admin0_data(CountryName="Sudan")
# Returns IDP data WITHOUT demographic disaggregation
DEFAULT_MAX_RETRIES = 3
DEFAULT_RETRY_DELAY = 1
DEFAULT_TIMEOUT = 30
get_all_countries(to_pandas: bool = True) → DataFrame | Dict[str, Any][source]

Retrieve all countries for which DTM data is publicly available through the API.

Returns:

All countries for which DTM data is publicly available through the API.

Return type:

Union[pd.DataFrame, Dict[str, Any]]

get_all_operations(to_pandas: bool = True) → DataFrame | Dict[str, Any][source]

Retrieve all operations for which DTM data is publicly available through the API.

Returns:

All operations for which DTM data is publicly available through the API.

Return type:

Union[pd.DataFrame, Dict[str, Any]]

get_idp_admin0_data(Operation: str | None = None, CountryName: str | None = None, Admin0Pcode: str | None = None, FromReportingDate: str | None = None, ToReportingDate: str | None = None, FromRoundNumber: int | None = None, ToRoundNumber: int | None = None, to_pandas: bool = True) → DataFrame | Dict[str, Any][source]

Retrieve IDP data at Admin 0 level based on specified parameters.

At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode.

Parameters:

  • Operation (Optional[str]) – Name of the DTM operation for which the data was collected.

  • CountryName (Optional[str]) – Name of the country where the data was collected.

  • Admin0Pcode (Optional[str]) – Country code (ISO 3166-1 alpha-3).

  • FromReportingDate (Optional[str]) – Start date for the reporting period (format: ‘YYYY-MM-DD’).

  • ToReportingDate (Optional[str]) – End date for the reporting period (format: ‘YYYY-MM-DD’).

  • FromRoundNumber (Optional[int]) – Starting round number for the data collection range.

  • ToRoundNumber (Optional[int]) – Ending round number for the data collection range.

  • to_pandas (bool) – If True, the data will be returned as a pandas DataFrame. Otherwise, it will be returned as a JSON object.

Returns:

The IDP Admin0 data matching the specified criteria, either as a DataFrame or a JSON object.

Return type:

Union[pd.DataFrame, Dict[str, Any]]

Raises:

ValidationError – If parameter validation fails.

get_idp_admin1_data(Operation: str | None = None, CountryName: str | None = None, Admin0Pcode: str | None = None, Admin1Name: str | None = None, Admin1Pcode: str | None = None, FromReportingDate: str | None = None, ToReportingDate: str | None = None, FromRoundNumber: int | None = None, ToRoundNumber: int | None = None, to_pandas: bool = True) → DataFrame | Dict[str, Any][source]

Retrieve IDP data at Admin 1 level based on specified parameters.

At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode.

Parameters:

  • Operation (Optional[str]) – Name of the DTM operation for which the data was collected.

  • CountryName (Optional[str]) – Name of the country where the data was collected.

  • Admin0Pcode (Optional[str]) – Country code (ISO 3166-1 alpha-3).

  • Admin1Name (Optional[str]) – Name of level 1 administrative boundaries.

  • Admin1Pcode (Optional[str]) – Place code of level 1 administrative boundaries.

  • FromReportingDate (Optional[str]) – Start date for the reporting period (format: ‘YYYY-MM-DD’).

  • ToReportingDate (Optional[str]) – End date for the reporting period (format: ‘YYYY-MM-DD’).

  • FromRoundNumber (Optional[int]) – Starting round number for the data collection range.

  • ToRoundNumber (Optional[int]) – Ending round number for the data collection range.

  • to_pandas (bool) – If True, the data will be returned as a pandas DataFrame. Otherwise, it will be returned as a JSON object.

Returns:

The IDP Admin1 data matching the specified criteria, either as a DataFrame or a JSON object.

Return type:

Union[pd.DataFrame, Dict[str, Any]]

Raises:

ValidationError – If parameter validation fails.

get_idp_admin2_data(Operation: str | None = None, CountryName: str | None = None, Admin0Pcode: str | None = None, Admin1Name: str | None = None, Admin1Pcode: str | None = None, Admin2Name: str | None = None, Admin2Pcode: str | None = None, FromReportingDate: str | None = None, ToReportingDate: str | None = None, FromRoundNumber: int | None = None, ToRoundNumber: int | None = None, to_pandas: bool = True) → DataFrame | Dict[str, Any][source]

Retrieve IDP data at Admin 2 level based on specified parameters.

At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode.

Parameters:

  • Operation (Optional[str]) – Name of the DTM operation for which the data was collected.

  • CountryName (Optional[str]) – Name of the country where the data was collected.

  • Admin0Pcode (Optional[str]) – Country code (ISO 3166-1 alpha-3).

  • Admin1Name (Optional[str]) – Name of level 1 administrative boundaries.

  • Admin1Pcode (Optional[str]) – Place code of level 1 administrative boundaries.

  • Admin2Name (Optional[str]) – Name of level 2 administrative boundaries.

  • Admin2Pcode (Optional[str]) – Place code of level 2 administrative boundaries.

  • FromReportingDate (Optional[str]) – Start date for the reporting period (format: ‘YYYY-MM-DD’).

  • ToReportingDate (Optional[str]) – End date for the reporting period (format: ‘YYYY-MM-DD’).

  • FromRoundNumber (Optional[int]) – Starting round number for the data collection range.

  • ToRoundNumber (Optional[int]) – Ending round number for the data collection range.

  • to_pandas (bool) – If True, the data will be returned as a pandas DataFrame. Otherwise, it will be returned as a JSON object.

Returns:

The IDP Admin2 data matching the specified criteria, either as a DataFrame or a JSON object.

Return type:

Union[pd.DataFrame, Dict[str, Any]]

Raises:

ValidationError – If parameter validation fails.

Exceptions

Custom exceptions for the DTM API client.

exception dtmapi.exceptions.DTMApiError[source]

Bases: Exception

Base exception for DTM API errors.

exception dtmapi.exceptions.DTMApiRequestError[source]

Bases: DTMApiError

Raised when a request to the API fails.

exception dtmapi.exceptions.DTMApiResponseError(message: str, error_messages: list = None)[source]

Bases: DTMApiError

Raised when the API returns an error response.

exception dtmapi.exceptions.DTMApiTimeoutError[source]

Bases: DTMApiError

Raised when a request to the API times out.

exception dtmapi.exceptions.DTMApiVersionError[source]

Bases: DTMApiError

Raised when an invalid API version is specified.

exception dtmapi.exceptions.DTMAuthenticationError[source]

Bases: DTMApiError

Raised when authentication with the API fails.

Validators

Input validation utilities for DTM API.

exception dtmapi.validators.ValidationError[source]

Bases: ValueError

Raised when input validation fails.

dtmapi.validators.validate_date_format(date_string: str, param_name: str) → None[source]

Validate that a date string is in YYYY-MM-DD format.

Parameters:

  • date_string (str) – The date string to validate.

  • param_name (str) – The parameter name for error messages.

Raises:

ValidationError – If date format is invalid.

dtmapi.validators.validate_date_range(from_date: str | None, to_date: str | None, from_param: str, to_param: str) → None[source]

Validate that date range is logical (from_date <= to_date).

Parameters:

  • from_date (Optional[str]) – Start date string.

  • to_date (Optional[str]) – End date string.

  • from_param (str) – Name of the from parameter.

  • to_param (str) – Name of the to parameter.

Raises:

ValidationError – If date range is invalid.

dtmapi.validators.validate_required_params(params: Dict[str, Any], required_one_of: List[str]) → None[source]

Validate that at least one of the required parameters is provided.

Parameters:

  • params (Dict[str, Any]) – Dictionary of parameters.

  • required_one_of (List[str]) – List of parameter names where at least one is required.

Raises:

ValidationError – If no required parameters are provided.

dtmapi.validators.validate_round_number_range(from_round: int | None, to_round: int | None) → None[source]

Validate round number range.

Parameters:

  • from_round (Optional[int]) – Starting round number.

  • to_round (Optional[int]) – Ending round number.

Raises:

ValidationError – If range is invalid.