TomTom Getting Started: Quick Integration Guide (2026)

Getting started overview

Integrating TomTom's location-based services into an application begins with setting up a developer account, obtaining necessary API credentials, and making an initial API call to verify the setup. TomTom offers a suite of APIs including Maps, Traffic, Routing, and Geocoding, alongside SDKs for web, Android, and iOS development, facilitating various use cases from automotive navigation to logistics management and real-time traffic updates. The process is designed to enable developers to quickly access and test the platform's capabilities using a free tier that provides 2,500 transactions per day. This guide focuses on the fundamental steps to get an application connected and making its first successful request.

The following table provides a quick reference for the initial setup:

Create an account and get keys

To begin using TomTom APIs, developers must first create an account on the TomTom Developer Portal. This account provides access to the developer dashboard, where API keys are managed and usage statistics can be monitored.

1. Navigate to the TomTom Developer Portal: Open your web browser and go to the TomTom Developer Portal registration page.
2. Sign Up: Click on the 'Sign up' or 'Register' button. You will typically be prompted to provide an email address, create a password, and agree to the terms of service.
3. Verify Email: After registration, TomTom usually sends a verification email. Follow the instructions in the email to activate your account.
4. Log In: Once your account is verified, log in to the TomTom Developer Dashboard.
5. Generate API Key: From the dashboard, navigate to the 'API Keys' section. Click on 'New Key' or a similar option to generate a new API key. You may be asked to provide a name for your application or key for organizational purposes. TomTom's API keys are generally used as a query parameter in API requests for authentication, as detailed in their TomTom API authentication guide.
6. Record Your API Key: Copy the generated API key and store it securely. This key will be required for all your API requests.

Your first request

After obtaining an API key, the next step is to make a simple request to confirm that your setup is correct. The TomTom Geocoding API is a suitable choice for a first request because it is straightforward, translating a human-readable address into geographic coordinates. This example will use a cURL command, which is a common command-line tool for making HTTP requests.

Example: Geocoding a specific address

We will use the Geocoding API to find the coordinates for '1600 Amphitheatre Parkway, Mountain View, CA'.

1. Identify the API Endpoint: The endpoint for the Geocoding API's search functionality is typically structured like https://api.tomtom.com/search/2/geocode/<query>.json.
2. Construct the Request URL: Replace <query> with the URL-encoded address and append your API key.

curl "https://api.tomtom.com/search/2/geocode/1600%20Amphitheatre%20Parkway%2C%20Mountain%20View%2C%20CA.json?key=YOUR_API_KEY"

Replace YOUR_API_KEY with the actual API key you generated.

Expected Successful Response (abbreviated):

A successful response will typically return a JSON object containing an array of results, with each result including detailed address information and geographic coordinates (latitude and longitude).

{
  "results": [
    {
      "position": {
        "lat": 37.42207,
        "lon": -122.08409
      },
      "address": {
        "streetNumber": "1600",
        "streetName": "Amphitheatre Parkway",
        "municipality": "Mountain View",
        "countryCode": "US",
        "country": "United States"
        // ... other address details
      },
      // ... other result details
    }
  ]
}

If you receive a JSON response similar to the above, your API key is correctly configured, and you have successfully made your first request to the TomTom API.

Common next steps

After successfully making a first API call, developers typically proceed with further exploration and integration:

• Explore Other APIs: TomTom offers a range of APIs beyond geocoding, including Map Display API, Traffic API, Routing API, and Search API. Review the TomTom API Explorer to understand the available functionalities and choose APIs relevant to your project.
• Utilize SDKs: For web and mobile applications, consider using TomTom's dedicated SDKs. The Web SDK simplifies map integration into web pages, while the Android SDK and iOS SDK provide native development environments for mobile applications. These SDKs handle many complexities of map rendering and interaction.
• Review Documentation: Dive deeper into the comprehensive TomTom API documentation for specific API endpoints, request parameters, response structures, and best practices.
• Implement Advanced Features: Once basic integration is complete, explore advanced features such as custom map styles, real-time traffic overlays, route optimization, and location-based search filters.
• Monitor Usage and Billing: Keep track of your API usage through the TomTom Developer Dashboard. Understand the TomTom pricing model to manage costs, especially as your application scales beyond the free tier.
• Secure API Keys: Implement security best practices for your API keys. Avoid embedding keys directly in client-side code without restrictions. For web applications, consider using domain restrictions, and for mobile apps, explore proxy servers or environment variables to protect your credentials.

Troubleshooting the first call

Encountering issues during the initial API call is common. Here are some typical problems and their solutions:

• 401 Unauthorized / Invalid API Key:
  • Issue: This error indicates that the API key provided is either missing, incorrect, or not authorized for the requested service.
  • Solution: Double-check that you have copied the API key correctly from your TomTom Developer Dashboard. Ensure there are no leading or trailing spaces. Verify that the key is appended as a key query parameter in your URL.
• 400 Bad Request:
  • Issue: This typically means there's an issue with the request parameters, such as missing required parameters or incorrect formatting.
  • Solution: Review the specific API's documentation (e.g., TomTom Geocoding API documentation) to confirm all required parameters are present and correctly formatted. Ensure that any special characters in the address query are URL-encoded (e.g., spaces become %20).
• Network Errors / Connection Refused:
  • Issue: This suggests a problem with your internet connection or a firewall blocking the request.
  • Solution: Verify your internet connection. If you are behind a corporate firewall, check if it's blocking outgoing requests to api.tomtom.com. Try making a request from a different network or device to isolate the issue.
• No Response / Timeout:
  • Issue: The request did not receive a response within a reasonable timeframe.
  • Solution: This could also be a network issue. Ensure the API endpoint URL is correct. TomTom's API status page (if available) or general network diagnostic tools can help identify broader outages or connectivity problems.
• Incorrect or Unexpected Data in Response:
  • Issue: The API returns data, but it's not what you expected.
  • Solution: Carefully review the request parameters you sent. For example, in Geocoding, ensure the address is precise. Consult the TomTom API reference for the expected response structure and potential error codes within the JSON body.
• CORS Issues (for Web Applications):
  • Issue: When integrating from a web browser, you might encounter Cross-Origin Resource Sharing (CORS) errors.
  • Solution: TomTom APIs generally support CORS for browser-based requests, but ensure your API key has appropriate domain restrictions configured in the developer dashboard if you are encountering issues. For local development, some browsers might require specific extensions or configurations, or you might need to proxy requests through your backend server. More broadly, the Mozilla Developer Network's CORS documentation provides a comprehensive overview of how CORS works.