API workflow overview

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)
   • 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):
     Copyaz storage blob upload --account-name "<STORAGE_ACCOUNT_NAME>" \ --container-name "default" \ --name "<YOUR_FILE_NAME>.parquet" \ --file "/path/to/<YOUR_FILE_NAME>.parquet" \ --auth-mode login

     1az 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

3. Job Execution

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

4. Results Download

   • Check output file schema in Output data schema
   • Download results using Azure CLI with storage credentials (replace placeholders with actual values):
     Copyaz storage blob download --account-name "<STORAGE_ACCOUNT_NAME>" \ --container-name "default" \ --name "<YOUR_FILE_NAME>.results.parquet" \ --file "/path/to/<YOUR_FILE_NAME>.results.parquet" \ --auth-mode login

     1az 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