API workflow

API workflow overview

A typical API-based workflow follows these steps:

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

Storage Access

List available storages (GET /storages)
Get storage credentials (GET /storages/{id}/credentials)
Finish Storage Authorization step to be authorized to access the storage with the obtained credentials
Make sure your data has the correct format, see Data preparation guide

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>.parquet" \
4
                     --file "/path/to/<YOUR_FILE_NAME>.parquet" \
5
                     --auth-mode login

Job Execution
- Create matching job (POST /jobs)
- Poll job status (GET /jobs/{job_id})
- Retrieve results when complete

Results Download

Check output file schema in Output data schema

Download results 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

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
Working with multiple jobs - Information about working with multiple matching jobs simultaneously
Private Data Gateway API - Learn how to manage your storage
GEM API - Learn how to run and monitor matching jobs