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:

• Contextual error messages relevant to SDK types (easier debugging)
• Prevention of malformed API calls (cost optimization)
• Early error detection in development

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

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

3
// Disable validation for specific services
4
await search({
5
    query: "Eiffel Tower",
6
    validateRequest: false
7
});
8

9
await geocode({
10
    query: "Amsterdam",
11
    validateRequest: false
12
});

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.

• onAPIRequest: Called immediately before the request is sent to the API.
• onAPIResponse: Called as soon as the raw response is received from the API, before parsing.

Example:

1
await search({
2
    query: "Eiffel Tower",
3
    onAPIRequest: (apiRequest) => {
4
        console.debug('API Request:', apiRequest);
5
    },
6
    onAPIResponse: (apiRequest, apiResponse) => {
7
        console.debug('API Response:', apiResponse);
8
    }
9
});

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.

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

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

Configuration Options:

• apiKey: Your TomTom API key (required)
• language: ISO language code for response localization
• baseUrl: Custom endpoint for enterprise or regional deployments
• timeout: Maximum request duration before timeout
• validateRequest: Global validation toggle

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:

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

3
try {
4
    const results = await search({
5
        query: "coffee",
6
        position: [4.9041, 52.3676]
7
    });
8

9
    console.log(results);
10
} catch (error) {
11
    // Handle specific error types
12
    if (error.status === 401) {
13
        console.error('Authentication failed - check API key');
14
        // Redirect to login or show API key configuration
15
    } else if (error.status === 429) {
16
        console.error('Rate limit exceeded - implement retry logic');
17
        // Implement exponential backoff retry
18
    } else if (error.status >= 500) {
19
        console.error('Server error - implement fallback');
20
        // Use cached data or alternative service
21
    } else {
22
        console.error('Request failed:', error.message);
23
        // Show user-friendly error message
24
    }
25
}

Common Error Codes:

• 400: Bad Request - Invalid parameters or malformed request
• 401: Unauthorized - Invalid or missing API key
• 403: Forbidden - API key lacks required permissions
• 429: Too Many Requests - Rate limit exceeded
• 500: Internal Server Error - Service temporarily unavailable

Custom Timeouts and Retry Logic

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

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

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

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:

• You need to transform requests or responses beyond standard SDK options.
• You want to integrate with custom API gateways, proxies, or non-standard endpoints.
• You require custom validation, error handling, or logging at the service layer.
• You need to adapt to new API versions or experimental features before official SDK support.

What does customizeService provide?

• Request builders: Functions to construct API requests with custom logic or parameters.
• Response parsers: Functions to transform or post-process API responses.
• Templates: Configuration objects that define service behavior.
• Validation schemas: Rules for input parameter validation.

Example usage:

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

3
// Access the request builder for geocoding
4
const { buildRequest } = customizeService.geocode;
5
const request = buildRequest({
6
  key: 'your-api-key',
7
  query: 'Amsterdam'
8
});
9

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

Related Guides and Examples

Related Guides

• Services Quickstart - Basic setup and usage patterns
• Places Services Quickstart - Places-specific configuration
• Routing Services Quickstart - Routing-specific configuration
• Core SDK Quickstart - Core configuration and setup

Configuration Examples

• Map Config Playground - Interactive configuration exploration
• Traffic Config Playground - Traffic service customization
• Node.js Examples - Server-side configuration patterns

Advanced Topics

• Service Customization - API Reference for advanced service customization options