Displacement Tracking Matrix

dtmapi is a Python package developed by Displacement Tracking Matrix (DTM). It empowers humanitarian actors, academia, media, governments, and non-governmental organizations to access non-sensitive Internally Displaced Person (IDP) figures, aggregated at multiple administrative levels:

  • Country Level (Admin 0)

  • First-level Administrative Divisions (Admin 1)

  • Second-level Administrative Divisions (Admin 2)

For more background, see the DTM API overview.

Key Features

  • API Version Support: Access both v3 (current) and v2 (legacy) API endpoints

  • Enhanced Data Fields (v3):

    • Gender Disaggregation: Male and female population breakdown

    • Origin of Displacement: Track geographical origins of displacement

    • Displacement Reason: Understand causes (conflict, disasters, etc.)

  • Robust Data Validation: Automatic validation of parameters (dates, ranges, required fields)

  • Automatic Retry Logic: Built-in exponential backoff for transient errors

  • Custom Exception Handling: Clear, specific error messages for different failure scenarios

  • Comprehensive Logging: Debug and track API interactions

  • Flexible Configuration: Customizable timeouts and retry settings

How to Get a Subscription API Key

Access to the DTM API now requires a personal API subscription key.

  1. Go to the DTM API Registration Portal: https://dtm-apim-portal.iom.int/

  2. Sign up or log in with personal details such as name, email, job title, and organization.

  3. In the APIs section, select API-V3.

  4. Click Subscribe. A subscription name may be requested—choose a meaningful name for identification.

  5. Once the subscription is activated, the API key can be accessed under the Profile section in the top menu bar.

    • The Primary key shown there serves as the personal API key.

    • The available endpoints for this API version are also listed.

  6. The API key should be copied and stored securely. It is required for authenticating all requests when using the dtmapi Python package.

Documentation

Full documentation is available at: https://dtmapi.readthedocs.io/en/latest/

Source Code

The source code for dtmapi is available on GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For any questions or feedback, please contact: dtmdataconsolidation@iom.int

Contents: