TomTom Maps SDK for JavaScript
This is the documentation of version 0.48.2. Go to the latest version, 1.0.0-rc.5.

Customizing services

The TomTom Maps SDK provides extensive configuration options to customize service behavior, optimize performance, and handle different application requirements. This guide covers request validation, custom configurations, error handling, and advanced service customization techniques.

Request Validation

The SDK includes built-in request validation that verifies each service request adheres to the expected structure before sending it to the API. This validation system helps developers catch errors early and prevents faulty API calls that could result in unnecessary costs.

Benefits of Request Validation:

Performance Considerations: If you're confident about your inputs and want to optimize CPU usage, you can disable validation on a per-service basis:

import { search, geocode, calculateRoute } from '@tomtom-org/maps-sdk/services';

// Disable validation for specific services
await search({
    query: "Eiffel Tower",
    validateRequest: false
});

await geocode({
    query: "Amsterdam",
    validateRequest: false
});

Recommendation: Keep validation enabled during development and testing phases. Only disable it in production when you're confident about input quality.

Service Lifecycle Hooks: onAPIRequest and onAPIResponse

The SDK allows you to hook into the service request lifecycle for advanced debugging, logging, or analytics. You can use the onAPIRequest and onAPIResponse callbacks to observe outgoing requests and incoming responses.

Example:

await search({
    query: "Eiffel Tower",
    onAPIRequest: (apiRequest) => {
        console.debug('API Request:', apiRequest);
    },
    onAPIResponse: (apiRequest, apiResponse) => {
        console.debug('API Response:', apiResponse);
    }
});

These hooks are useful for debugging, analytics, or custom logging. They do not modify the request or response.

Global Service Configuration

The TomTomConfig class provides centralized configuration management for all SDK services. This approach ensures consistent behavior across your application and simplifies configuration management.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';

TomTomConfig.instance.put({
    apiKey: 'YOUR_API_KEY',
    language: 'en-GB',                    // Default language for all responses
    baseUrl: 'https://api.tomtom.com',    // Custom API base URL for enterprise
    timeout: 10000,                       // Global request timeout (milliseconds)
    validateRequest: false                // Global validation setting
});

Configuration Options:

Comprehensive Error Handling

Robust error handling is crucial for production applications. The SDK provides structured error responses that help you implement appropriate user feedback and fallback strategies:

import { search } from '@tomtom-org/maps-sdk/services';

try {
    const results = await search({
        query: "coffee",
        position: [4.9041, 52.3676]
    });

    console.log(results);
} catch (error) {
    // Handle specific error types
    if (error.status === 401) {
        console.error('Authentication failed - check API key');
        // Redirect to login or show API key configuration
    } else if (error.status === 429) {
        console.error('Rate limit exceeded - implement retry logic');
        // Implement exponential backoff retry
    } else if (error.status >= 500) {
        console.error('Server error - implement fallback');
        // Use cached data or alternative service
    } else {
        console.error('Request failed:', error.message);
        // Show user-friendly error message
    }
}

Common Error Codes:

Custom Timeouts and Retry Logic

Different services may require different timeout configurations based on complexity and expected response times:

// Short timeout for autocomplete (fast response expected)
await autocompleteSearch({
    query: "coffee",
    position: [4.9041, 52.3676],
    timeout: 3000 // 3 seconds
});

// Longer timeout for complex routing calculations
await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    timeout: 15000 // 15 seconds
});

Advanced Customization

For advanced use cases, the SDK exposes the customizeService object, which provides low-level access to the internal components of each service. This enables you to deeply customize how requests are built, how responses are parsed, and how the service logic operates.

When to use customizeService:

What does customizeService provide?

Example usage:

import { customizeService } from '@tomtom-org/maps-sdk/services';

// Access the request builder for geocoding
const { buildRequest } = customizeService.geocode;
const request = buildRequest({
  key: 'your-api-key',
  query: 'Amsterdam'
});

// Use the response parser for custom handling
const { parseResponse } = customizeService.geocode;
const rawApiResponse = await fetch(request.url);
const parsedData = parseResponse(await rawApiResponse.json());

Note: Most developers will not need to use customizeService directly. The standard service functions (like geocode, search, calculateRoute) are sufficient for typical use cases. Use advanced customization only when you need to modify internal service behavior.

Related Guides and Examples

Related Guides

Configuration Examples

Advanced Topics