API workflow

API workflow

A typical API-based workflow follows these steps:

1. Authentication

   • Finish Obtaining a TomTom API key step to get your API key
   • Finish Obtaining an authorization token step to get your Authorization token from Azure CLI

2. Storage access

   • List available storages (GET /storages). The host name of the storage url starts with the storage account name that Azure CLI needs, for example mystorageaccount001 in https://mystorageaccount001.blob.core.windows.net/default/. The container name is always default.
   • Get storage credentials (GET /storages/{id}/credentials)
   • Finish Storage Authorization step to be authorized to access the storage with the obtained credentials

3. Data upload

   • Make sure your data has the correct format, see Data preparation
   • Upload data using Azure CLI (replace placeholders with actual values):

     1
     az storage blob upload --account-name "<STORAGE_ACCOUNT_NAME>" \
     2
                          --container-name "default" \
     3
                          --name "<YOUR_FILE_NAME>" \
     4
                          --file "/path/to/<YOUR_FILE_NAME>" \
     5
                          --auth-mode login

   • Confirm the upload with List storage files (GET /storages/{id}/files). Use the path of your file as filename when you create the job.

4. Job execution

   • Create matching job (POST /jobs)
   • Poll job status (GET /jobs/{job_id}) until it is SUCCESS, FAILED, or CANCELED. For a FAILED job, error_messages explains why it failed.
   • Optionally, cancel a job that is no longer needed (PATCH /jobs/{job_id})

5. Results download

   • Check the results format: road matching results or lane-level matching results
   • Download the file named in result_filename using Azure CLI with storage credentials (replace placeholders with actual values):

     1
     az storage blob download --account-name "<STORAGE_ACCOUNT_NAME>" \
     2
                             --container-name "default" \
     3
                             --name "<YOUR_FILE_NAME>.results.parquet" \
     4
                             --file "/path/to/<YOUR_FILE_NAME>.results.parquet" \
     5
                             --auth-mode login

   • For road matching jobs created with with_visualization_data: true, download the GeoJSON files as described in Visualization data

Resources

• Troubleshooting - Check solutions in case of issues
• API Authentication - Learn how to authenticate API requests
• Storage Authentication - Learn how to access storage with obtained credentials
• Data preparation - Learn how to prepare your input file
• Private Data Gateway API - Learn how to manage your storage
• GEM API - Learn how to run and monitor matching jobs