@tomtom-org/maps-sdk 0.45.12 → 0.46.0

package/services/dist/index.d.ts

@@ -6,7 +6,6 @@ import { ChargingStation } from '@tomtom-org/maps-sdk/core';
 import { ChargingStationsAccessType } from '@tomtom-org/maps-sdk/core';
 import { ChargingStationsAvailability } from '@tomtom-org/maps-sdk/core';
 import { ChargingStopProps } from '@tomtom-org/maps-sdk/core';
-import { Classification } from '@tomtom-org/maps-sdk/core';
 import { CommonPlaceProps } from '@tomtom-org/maps-sdk/core';
 import { Connector } from '@tomtom-org/maps-sdk/core';
 import { ConnectorType } from '@tomtom-org/maps-sdk/core';
@@ -39,6 +38,7 @@ import { Places as Places_2 } from '@tomtom-org/maps-sdk/core';
 import { PlaceType } from '@tomtom-org/maps-sdk/core';
 import { PlugType } from '@tomtom-org/maps-sdk/core';
 import { POICategory } from '@tomtom-org/maps-sdk/core';
+import { POICategory as POICategory_2 } from '@tomtom-org/maps-sdk/core';
 import { Point } from 'geojson';
 import { Polygon } from 'geojson';
 import { PolygonFeature } from '@tomtom-org/maps-sdk/core';
@@ -58,6 +58,7 @@ import { SearchPlaceProps as SearchPlaceProps_2 } from '@tomtom-org/maps-sdk/cor
 import { SideOfStreet } from '@tomtom-org/maps-sdk/core';
 import { TimeZone } from '@tomtom-org/maps-sdk/core';
 import { TomTomHeaders } from '@tomtom-org/maps-sdk/core';
+import { TrafficAreaAnalytics } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentCategory } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentDetails } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentTEC } from '@tomtom-org/maps-sdk/core';
@@ -99,6 +100,15 @@ declare type AddressRangesAPI = {
     to: LatLonAPI;
 };
 
+/**
+ * @ignore
+ */
+declare type AnomalyAPI = {
+    startDate: string;
+    endDate: string;
+    labels: string[];
+};
+
 /**
  * @ignore
  */
@@ -129,6 +139,89 @@ declare type APIErrorResponse<T = DefaultAPIResponseErrorBody> = {
     data?: T;
 };
 
+/**
+ * @ignore
+ */
+declare type AreaAnalyticsCollectionPropertiesAPI = {
+    startDate: string;
+    endDate: string;
+    dataTypes: string[];
+    heatmap: boolean;
+    frcs: number[];
+};
+
+/**
+ * A traffic metric that can be requested in an area analytics report.
+ *
+ * @group Traffic
+ */
+export declare type AreaAnalyticsDataType = (typeof areaAnalyticsDataTypes)[number];
+
+/**
+ * Valid data-type identifiers for area analytics requests.
+ *
+ * @group Traffic
+ */
+export declare const areaAnalyticsDataTypes: readonly ["NETWORK_LENGTH", "CONGESTION_LEVEL", "FREE_FLOW_SPEED", "TRAVEL_TIME", "SPEED"];
+
+/**
+ * A date value accepted by Traffic Area Analytics — either a `Date` object or
+ * an ISO `'YYYY-MM-DD'` string.
+ * `Date` objects are automatically converted to `YYYY-MM-DD` format before
+ * being sent to the API.
+ *
+ * @group Traffic
+ */
+export declare type AreaAnalyticsDateInput = string | Date;
+
+/**
+ * @ignore
+ */
+declare type AreaAnalyticsFeatureAPI = {
+    type: 'Feature';
+    id: string;
+    geometry: Polygon;
+    properties: FeaturePropertiesAPI;
+};
+
+/**
+ * @ignore
+ */
+declare type AreaAnalyticsRequestBody = {
+    name?: string;
+    /** Continuous range start — mutually exclusive with `days`. */
+    startDate?: string;
+    /** Continuous range end — mutually exclusive with `days`. */
+    endDate?: string;
+    /** Specific dates — mutually exclusive with `startDate`/`endDate`. */
+    days?: string[];
+    dataTypes: string[];
+    frcs: number[];
+    hours: number[];
+    features: AreaAnalyticsRequestBodyFeature[];
+};
+
+/**
+ * @ignore
+ */
+declare type AreaAnalyticsRequestBodyFeature = {
+    type: 'Feature';
+    properties?: {
+        name?: string;
+        timezone?: string;
+    };
+    geometry: Polygon | MultiPolygon;
+};
+
+/**
+ * @ignore
+ */
+declare type AreaAnalyticsResponseAPI = {
+    type: 'FeatureCollection';
+    properties: AreaAnalyticsCollectionPropertiesAPI;
+    features: AreaAnalyticsFeatureAPI[];
+};
+
 /**
  * Base properties shared across all autocomplete segment types.
  *
@@ -192,7 +285,6 @@ export declare type AutocompleteGenericSearchSegment = {
  * ```typescript
  * // Autocomplete as user types "amster"
  * const suggestions = await autocompleteSearch({
- *   key: 'your-api-key',
  *   query: 'amster',
  *   limit: 5
  * });
@@ -200,18 +292,17 @@ export declare type AutocompleteGenericSearchSegment = {
  *
  * // Autocomplete with position bias
  * const localSuggestions = await autocompleteSearch({
- *   key: 'your-api-key',
  *   query: 'main st',
- *   at: [4.9041, 52.3676],  // Near Amsterdam
+ *   position: [4.9041, 52.3676],  // Near Amsterdam
  *   limit: 10
  * });
  *
- * // Autocomplete with category filter
- * const restaurantSuggestions = await autocompleteSearch({
- *   key: 'your-api-key',
+ * // Autocomplete restricted to a country with radius
+ * const nlSuggestions = await autocompleteSearch({
  *   query: 'pizz',
- *   categorySet: [7315],  // Restaurant category
- *   at: [4.9041, 52.3676]
+ *   countries: ['NL'],
+ *   position: [4.9041, 52.3676],
+ *   radiusMeters: 5000
  * });
  * ```
  *
@@ -248,12 +339,12 @@ export declare type AutocompleteSearchBrandSegment = AutocompleteGenericSearchSe
 export declare type AutocompleteSearchCategorySegment = AutocompleteGenericSearchSegment & {
     type: 'category';
     /**
-     * Category identifier for filtering search results.
+     * The recognized POI category.
      *
      * Use with the poiCategories parameter in other search endpoints
      * to restrict results to POIs of this category.
      */
-    id: string;
+    category: POICategory;
     /**
      * Alternative name that matched the user query.
      *
@@ -265,6 +356,15 @@ export declare type AutocompleteSearchCategorySegment = AutocompleteGenericSearc
     matchedAlternativeName?: string;
 };
 
+/**
+ * @ignore
+ */
+export declare type AutocompleteSearchCategorySegmentAPI = AutocompleteGenericSearchSegment & {
+    type: 'category';
+    id: string;
+    matchedAlternativeName?: string;
+};
+
 /**
  * Context information for an autocomplete search request.
  *
@@ -543,7 +643,7 @@ export declare type AutocompleteSearchResponse = {
  */
 export declare type AutocompleteSearchResponseAPI = {
     context: AutocompleteSearchContextAPI;
-    results: AutocompleteSearchResult[];
+    results: AutocompleteSearchResultAPI[];
 };
 
 /**
@@ -564,6 +664,13 @@ export declare type AutocompleteSearchResult = {
     segments: AutocompleteSearchSegment[];
 };
 
+/**
+ * @ignore
+ */
+export declare type AutocompleteSearchResultAPI = {
+    segments: AutocompleteSearchSegmentAPI[];
+};
+
 /**
  * Geographic bias parameters for autocomplete search results.
  *
@@ -605,6 +712,11 @@ export declare type AutocompleteSearchResultGeoBiasAPI = {
  */
 export declare type AutocompleteSearchSegment = AutocompleteSearchBrandSegment | AutocompleteSearchCategorySegment | AutocompleteSearchPlaintextSegment;
 
+/**
+ * @ignore
+ */
+export declare type AutocompleteSearchSegmentAPI = AutocompleteSearchBrandSegment | AutocompleteSearchCategorySegmentAPI | AutocompleteSearchPlaintextSegment;
+
 /**
  * Segment type for autocomplete results.
  *
@@ -834,6 +946,12 @@ export declare const buildResponseError: (error: unknown, serviceName: ServiceNa
  */
 declare const buildRevGeoRequest: (params: ReverseGeocodingParams) => URL;
 
+/**
+ * Default method for building a Traffic Area Analytics request from {@link TrafficAreaAnalyticsParams}.
+ * @param params The traffic area analytics parameters, with global configuration already merged.
+ */
+declare const buildTrafficAreaAnalyticsRequest: (params: TrafficAreaAnalyticsParams) => FetchInput<AreaAnalyticsRequestBody>;
+
 /**
  * Default method for building a traffic incident details request from {@link TrafficIncidentDetailsParams}.
  * @param params The traffic incident details parameters, with global configuration already merged into them.
@@ -2025,23 +2143,20 @@ export declare type CommonGeocodeAndFuzzySearchParams = {
  *
  * @example
  * ```typescript
- * // Basic search with position bias
+ * // Search with position bias
  * const searchParams: CommonPlacesParams<URL, Response> = {
- *   query: 'pizza restaurant',
  *   position: [4.9041, 52.3676],  // Near Amsterdam
  *   limit: 20
  * };
  *
  * // Search with geography type filter
  * const citySearch: CommonPlacesParams<URL, Response> = {
- *   query: 'Paris',
  *   geographyTypes: ['Municipality'],  // Only cities
  *   limit: 10
  * };
  *
  * // Search with mapcodes and specific geopolitical view
  * const detailedSearch: CommonPlacesParams<URL, Response> = {
- *   query: 'disputed location',
  *   view: 'IN',  // India's perspective
  *   mapcodes: ['Local', 'International'],
  *   extendedPostalCodesFor: ['PAD', 'POI'],
@@ -2050,7 +2165,6 @@ export declare type CommonGeocodeAndFuzzySearchParams = {
  *
  * // Address search with extended postal codes
  * const addressSearch: CommonPlacesParams<URL, Response> = {
- *   query: '123 Main Street',
  *   geographyTypes: ['Country', 'Municipality'],
  *   extendedPostalCodesFor: ['Geo', 'PAD', 'Addr'],
  *   limit: 15
@@ -2060,30 +2174,6 @@ export declare type CommonGeocodeAndFuzzySearchParams = {
  * @group Search
  */
 export declare type CommonPlacesParams<ApiRequest, ApiResponse> = CommonServiceParams<ApiRequest, ApiResponse> & {
-    /**
-     * Search query string.
-     *
-     * The text to search for - can be an address, place name, POI, or general location query.
-     * Must be properly URL encoded when sent to the API.
-     *
-     * @remarks
-     * **Query Examples:**
-     * - Street addresses: "123 Main Street, New York"
-     * - Place names: "Eiffel Tower", "Central Park"
-     * - POI names: "Starbucks", "McDonald's"
-     * - General queries: "pizza near me", "gas station"
-     * - Partial inputs: "Amst" (for autocomplete)
-     *
-     * The query is processed with fuzzy matching to handle typos and variations.
-     *
-     * @example
-     * ```typescript
-     * query: "1600 Pennsylvania Avenue, Washington DC"
-     * query: "Amsterdam Central Station"
-     * query: "coffee shop"
-     * ```
-     */
-    query: string;
     /**
      * Geographic position to bias search results.
      *
@@ -2442,6 +2532,31 @@ export declare type CommonRoutingParams = {
  * @group Search
  */
 export declare type CommonSearchParams<ApiRequest, ApiResponse> = CommonPlacesParams<ApiRequest, ApiResponse> & {
+    /**
+     * Search query string.
+     *
+     * The text to search for — can be a place name, POI, address, or any free-form location query.
+     * When omitted, results are driven entirely by other filters such as {@link poiCategories},
+     * {@link poiBrands}, {@link fuelTypes}, or {@link geometries}.
+     *
+     * @remarks
+     * **Query Examples:**
+     * - Place/POI names: "Eiffel Tower", "Starbucks"
+     * - General queries: "pizza near me", "gas station"
+     * - Partial inputs: "Amst" (for autocomplete / typeahead)
+     *
+     * The query is processed with fuzzy matching to handle typos and variations.
+     *
+     * @example
+     * ```typescript
+     * // Text-driven search
+     * query: 'coffee shop'
+     *
+     * // Omit query to search purely by category
+     * poiCategories: ['ELECTRIC_VEHICLE_STATION']
+     * ```
+     */
+    query?: string;
     /**
      * Specify which search indexes to query.
      *
@@ -2476,35 +2591,31 @@ export declare type CommonSearchParams<ApiRequest, ApiResponse> = CommonPlacesPa
      * Filter results to specific POI categories.
      *
      * Restricts results to Points of Interest belonging to the specified
-     * categories. Use category IDs from the POI Categories API.
+     * categories. Use values from the {@link POICategory} type.
      *
      * @remarks
-     * **Category Examples:**
-     * - 7315: Restaurant
-     * - 7311: Petrol/Gas Station
-     * - 7313: Hotel/Motel
-     * - 7832: ATM
-     * - 9361: Parking
-     *
      * **Multiple Categories:**
      * Results include POIs matching ANY of the specified categories (OR logic).
      *
-     * **Discovery:**
-     * Use the POI Categories endpoint to browse all available categories.
+     * **Discovering Categories:**
+     * Use the {@link getPOICategories} service to search and browse available
+     * categories by name or synonym, then pass the resulting `code` values here.
      *
      * @example
      * ```typescript
-     * // Restaurants only
-     * poiCategories: [7315]
+     * // Filter to specific categories
+     * poiCategories: ['RESTAURANT', 'CAFE']
      *
-     * // Restaurants and cafes
-     * poiCategories: [7315, 9376]
+     * // Category-only search (no query)
+     * poiCategories: ['ELECTRIC_VEHICLE_STATION']
      *
-     * // Gas stations and EV charging
-     * poiCategories: [7311, 7309]
+     * // Discovered via getPOICategories() service
+     * import { getPOICategoryCodes } from '@tomtom-org/maps-sdk/services';
+     * const codes = await getPOICategoryCodes({ filters: ['italian'] });
+     * const results = await search({ poiCategories: codes, position });
      * ```
      */
-    poiCategories?: (number | POICategory)[];
+    poiCategories?: POICategory[];
     /**
      * Filter results to specific POI brands.
      *
@@ -3134,6 +3245,12 @@ declare const customize: {
 };
 
 declare const customize_10: {
+    buildPlaceByIdRequest: typeof buildPlaceByIdRequest;
+    parsePlaceByIdResponse: typeof parsePlaceByIdResponse;
+    placeByIdTemplate: PlaceByIdTemplate;
+};
+
+declare const customize_11: {
     autocompleteSearch: typeof autocompleteSearch;
     buildAutocompleteSearchRequest: typeof buildAutocompleteSearchRequest;
     parseAutocompleteSearchResponse: typeof parseAutocompleteSearchResponse;
@@ -3178,15 +3295,15 @@ declare const customize_7: {
 };
 
 declare const customize_8: {
-    buildTrafficIncidentDetailsRequest: typeof buildTrafficIncidentDetailsRequest;
-    parseTrafficIncidentDetailsResponse: typeof parseTrafficIncidentDetailsResponse;
-    trafficIncidentDetailsTemplate: TrafficIncidentDetailsTemplate;
+    buildTrafficAreaAnalyticsRequest: typeof buildTrafficAreaAnalyticsRequest;
+    parseTrafficAreaAnalyticsResponse: typeof parseTrafficAreaAnalyticsResponse;
+    trafficAreaAnalyticsTemplate: TrafficAreaAnalyticsTemplate;
 };
 
 declare const customize_9: {
-    buildPlaceByIdRequest: typeof buildPlaceByIdRequest;
-    parsePlaceByIdResponse: typeof parsePlaceByIdResponse;
-    placeByIdTemplate: PlaceByIdTemplate;
+    buildTrafficIncidentDetailsRequest: typeof buildTrafficIncidentDetailsRequest;
+    parseTrafficIncidentDetailsResponse: typeof parseTrafficIncidentDetailsResponse;
+    trafficIncidentDetailsTemplate: TrafficIncidentDetailsTemplate;
 };
 
 /**
@@ -3239,9 +3356,10 @@ export declare const customizeService: {
     calculateRoute: typeof customize_5;
     reachableRange: typeof customize_6;
     evChargingStationsAvailability: typeof customize_7;
-    trafficIncidentDetails: typeof customize_8;
-    placeByID: typeof customize_9;
-    autocompleteSearch: typeof customize_10;
+    trafficAreaAnalytics: typeof customize_8;
+    trafficIncidentDetails: typeof customize_9;
+    placeByID: typeof customize_10;
+    autocompleteSearch: typeof customize_11;
 };
 
 /**
@@ -3789,6 +3907,28 @@ declare type ExplicitVehicleModel<E extends VehicleEngineType> = {
  */
 export declare type ExtendedRouteRepresentation = 'distance' | 'travelTime';
 
+/**
+ * @ignore
+ */
+declare type FeaturePropertiesAPI = {
+    name: string;
+    timezone: string;
+    level: number;
+    baseData: MetricsAPI;
+    timedData: {
+        yearly?: TimedEntryAPI[];
+        monthly?: TimedEntryAPI[];
+        weekly?: TimedEntryAPI[];
+        daily?: TimedEntryAPI[];
+        hourly?: TimedEntryAPI[];
+        average?: TimedEntryAPI[];
+    };
+    tiledData?: {
+        tiles: TiledEntryAPI[];
+    };
+    anomalies?: Record<string, AnomalyAPI[]>;
+};
+
 /**
  * Hybrid HTTP fetch input, supporting different HTTP methods such as GET and POST.
  * * GET method comes with a URL.
@@ -3802,6 +3942,38 @@ export declare type FetchInput<PostData = void> = {
     method: 'POST';
 } & PostObject<PostData>);
 
+/**
+ * A Functional Road Class (FRC) identifier — classifies road segments by their importance
+ * in the road network.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `'MOTORWAY'` | Motorways, freeways, and major roads |
+ * | `'MAJOR_ROAD'` | Major roads, less important than motorways |
+ * | `'OTHER_MAJOR_ROAD'` | Other major roads connecting neighbouring regions |
+ * | `'SECONDARY_ROAD'` | Secondary roads linking parts of the same region |
+ * | `'LOCAL_CONNECTING_ROAD'` | Local roads providing settlement access |
+ * | `'LOCAL_ROAD_HIGH_IMPORTANCE'` | Local roads of high importance within a settlement |
+ * | `'LOCAL_ROAD'` | Local roads within settlement sections |
+ * | `'LOCAL_ROAD_MINOR_IMPORTANCE'` | Local roads of minor importance (dead-ends, alleys) |
+ * | `'OTHER_ROAD'` | Other roads (paths, cycle routes, pedestrian infrastructure) |
+ *
+ * @group Traffic
+ */
+export declare type FunctionalRoadClass = (typeof functionalRoadClasses)[number];
+
+/**
+ * Ordered list of Functional Road Class identifiers, from highest importance (motorways) to lowest.
+ *
+ * @remarks
+ * The index of each class in this array corresponds to its FRC value in the API (0 for 'MOTORWAY', 1 for 'MAJOR_ROAD', ..., 8 for 'OTHER_ROAD').
+ *
+ * @see https://docs.tomtom.com/traffic-stats/documentation/product-information/faq#what-are-functional-road-classes-frc
+ *
+ * @group Traffic
+ */
+export declare const functionalRoadClasses: readonly ["MOTORWAY", "MAJOR_ROAD", "OTHER_MAJOR_ROAD", "SECONDARY_ROAD", "LOCAL_CONNECTING_ROAD", "LOCAL_ROAD_HIGH_IMPORTANCE", "LOCAL_ROAD", "LOCAL_ROAD_MINOR_IMPORTANCE", "OTHER_ROAD"];
+
 /**
  * Additional properties for fuzzy search feature collection.
  *
@@ -4099,8 +4271,24 @@ export declare type GenericVehicleState = {
 export declare const geocode: (params: GeocodingParams, customTemplate?: Partial<GeocodingTemplate>) => Promise<GeocodingResponse>;
 
 /**
+ * Geocode a query and return the single best-matching place.
+ *
+ * Convenience wrapper around {@link geocode} that returns the top result directly.
+ *
+ * @param query - Address or place name to geocode
+ * @returns Promise resolving to the best-matching place
+ * @throws {Error} If no results are found for the query
+ *
+ * @remarks
+ * Use {@link geocode} with a `limit` parameter when you need to handle the case
+ * where no results are found without throwing.
+ *
+ * @example
+ * ```typescript
+ * const place = await geocodeOne('Amsterdam Centraal');
+ * console.log(place.geometry.coordinates); // [lng, lat]
+ * ```
  *
- * @param query
  * @group Geocoding
  */
 export declare const geocodeOne: (query: string) => Promise<Place<GeocodingProps>>;
@@ -4144,6 +4332,29 @@ declare type GeocodingIndexTypesAbbreviation = Exclude<SearchIndexType, 'POI'>;
  * @group Geocoding
  */
 export declare type GeocodingParams = Omit<CommonPlacesParams<URL, GeocodingResponseAPI> & CommonGeocodeAndFuzzySearchParams, 'extendedPostalCodesFor'> & {
+    /**
+     * Address or location query to geocode.
+     *
+     * The text to convert into geographic coordinates — typically a street address,
+     * intersection, city name, or landmark. The service is tolerant of typos and
+     * incomplete inputs.
+     *
+     * @remarks
+     * **Query Examples:**
+     * - Full street address: "1600 Pennsylvania Avenue NW, Washington, DC"
+     * - City name: "Amsterdam"
+     * - Intersection: "Broadway & 42nd St, New York"
+     * - Landmark: "Eiffel Tower, Paris"
+     * - Partial address: "Dam Square" (city context resolved via `position` or `countries`)
+     *
+     * @example
+     * ```typescript
+     * query: '1600 Pennsylvania Avenue NW, Washington, DC'
+     * query: 'Museumplein, Amsterdam'
+     * query: 'Buckingham Palace, London'
+     * ```
+     */
+    query: string;
     /**
      * Indexes for which extended postal codes should be included in the results.
      *
@@ -4505,7 +4716,6 @@ export declare type GeometryPlaceParams = CommonServiceParamsWithZoom & {
  * ```typescript
  * // Search within a polygon (neighborhood boundaries)
  * const inArea = await geometrySearch({
- *   key: 'your-api-key',
  *   query: 'coffee shop',
  *   geometries: [{
  *     type: 'Polygon',
@@ -4519,20 +4729,15 @@ export declare type GeometryPlaceParams = CommonServiceParamsWithZoom & {
  *   }]
  * });
  *
- * // Find POIs along a route corridor
+ * // Find POIs along a route (pass the route LineString as geometry)
  * const alongRoute = await geometrySearch({
- *   key: 'your-api-key',
  *   query: 'gas station',
- *   geometries: [routeLineString],  // From calculateRoute result
- *   geometryList: [{
- *     position: 0,
- *     radius: 5000  // 5km corridor along route
- *   }]
+ *   geometries: [routeLineString],  // LineString from calculateRoute result
+ *   limit: 10
  * });
  *
  * // Search multiple areas at once
  * const multiArea = await geometrySearch({
- *   key: 'your-api-key',
  *   query: 'pharmacy',
  *   geometries: [polygonA, polygonB, polygonC],
  *   limit: 20
@@ -4540,8 +4745,7 @@ export declare type GeometryPlaceParams = CommonServiceParamsWithZoom & {
  *
  * // Category search within geometry
  * const restaurants = await geometrySearch({
- *   key: 'your-api-key',
- *   categorySet: [7315],  // Restaurant category
+ *   poiCategories: ['ITALIAN_RESTAURANT'],
  *   geometries: [cityBoundary]
  * });
  * ```
@@ -4818,6 +5022,60 @@ export declare function getPlacesWithEVAvailability<P extends CommonPlaceProps =
  */
 export declare const getPlaceWithEVAvailability: <P extends CommonPlaceProps = CommonPlaceProps>(place: Place<P>) => Promise<Place<EVChargingStationWithAvailabilityPlaceProps> | undefined>;
 
+/**
+ * Retrieve the list of POI category types supported by the TomTom Search API.
+ *
+ * The returned `code` values (`POICategory`) serve two purposes:
+ * - Pass to `search({ poiCategories })` to filter search results by category.
+ * - Pass to `POIsModule.filterCategories()` to filter the map's built-in POI icons.
+ *   Generic parent codes (e.g. `'RESTAURANT'`) are supported there; overly specific child
+ *   codes (e.g. `'ITALIAN_RESTAURANT'`) are not — use a parent or a `POICategoryGroup` instead.
+ *
+ * Results are cached in memory per language. The first call fetches from the API;
+ * all subsequent calls — including filtered ones — are served from the cache.
+ *
+ * @param params - Optional parameters. Uses global `TomTomConfig` by default.
+ *
+ * @example
+ * ```typescript
+ * // All categories
+ * const { poiCategories: all } = await getPOICategories();
+ *
+ * // Filtered by keyword, merged and deduplicated
+ * const { poiCategories: gyms } = await getPOICategories({ filters: ['gym'] });
+ * gyms.forEach(c => console.log(c.code, c.name, c.childCategoryCodes));
+ * ```
+ *
+ * @group POI Categories
+ */
+export declare const getPOICategories: (params?: POICategoriesParams) => Promise<POICategoriesResponse>;
+
+/**
+ * Convenience wrapper around {@link getPOICategories} that returns a flat array of `POICategory` codes.
+ *
+ * The returned codes serve two purposes:
+ * - Pass to `search({ poiCategories })` to filter search results by category.
+ * - Pass to `POIsModule.filterCategories()` to filter the map's built-in POI icons.
+ *   Generic parent codes (e.g. `'RESTAURANT'`) are supported there; overly specific child
+ *   codes (e.g. `'ITALIAN_RESTAURANT'`) are not — use a parent or a `POICategoryGroup` instead.
+ *
+ * Accepts the same parameters as {@link getPOICategories} — use `filters` to narrow by keyword.
+ *
+ * @param params - Optional parameters. Uses global `TomTomConfig` by default.
+ *
+ * @example
+ * ```typescript
+ * // All category codes
+ * const codes = await getPOICategoryCodes();
+ *
+ * // Codes matching 'restaurant' — for search or generic map POI filtering
+ * const restaurantCodes = await getPOICategoryCodes({ filters: ['restaurant'] });
+ * ```
+ *
+ * @group POI Categories
+ */
+export declare const getPOICategoryCodes: (params?: POICategoriesParams) => Promise<POICategory_2[]>;
+
 /**
  * @ignore
  */
@@ -5103,6 +5361,18 @@ declare const loadTypes: readonly ["USHazmatClass1", "USHazmatClass2", "USHazmat
  */
 export declare type MaxNumberOfAlternatives = 0 | 1 | 2 | 3 | 4 | 5;
 
+/**
+ * @ignore
+ * Abbreviated metric fields as returned by the Area Analytics API.
+ */
+declare type MetricsAPI = {
+    v?: number;
+    fv?: number;
+    c?: number;
+    t?: number;
+    l?: number;
+};
+
 /**
  * @ignore
  */
@@ -5286,6 +5556,12 @@ export declare type ParseResponseError<T = DefaultAPIResponseErrorBody> = (apiEr
  */
 declare const parseRevGeoResponse: (apiResponse: ReverseGeocodingResponseAPI, params: ReverseGeocodingParams) => ReverseGeocodingResponse;
 
+/**
+ * Default method for parsing a Traffic Area Analytics API response.
+ * @param apiResponse The raw Area Analytics API response.
+ */
+declare const parseTrafficAreaAnalyticsResponse: (apiResponse: AreaAnalyticsResponseAPI) => TrafficAreaAnalytics;
+
 /**
  * Default method for parsing a traffic incident details API response.
  * @param apiResponse The raw Traffic Incident Details API response.
@@ -5567,10 +5843,106 @@ declare type POIAPI = {
     categorySet?: CategoryAPI[];
     categories?: string[];
     openingHours?: OpeningHoursAPI;
-    classifications?: Classification[];
     timeZone?: TimeZone;
 };
 
+/**
+ * Parameters for the POI categories service.
+ *
+ * Results are cached in memory per language — the first call for a given language
+ * fetches from the API; subsequent calls are served from the cache.
+ *
+ * @group POI Categories
+ */
+export declare type POICategoriesParams = CommonServiceParams<URL, PoiCategoriesResponseAPI> & {
+    /**
+     * One or more filter strings applied client-side against the text index.
+     *
+     * Each filter string is normalized (lowercased, spaces removed) and matched against
+     * the normalized form of every `name` and synonym. A category matches when any of its
+     * normalized texts contains the normalized filter as a substring.
+     *
+     * For example, `'gym'` matches a category whose name or synonym normalizes to `'gym'`
+     * or `'fitnessandgym'`. `'italian restaurant'` normalizes to `'italianrestaurant'` and
+     * matches `'Italian Restaurant'` but not `'Mexican Restaurant'`.
+     *
+     * Results from all filter strings are merged and deduplicated by `code`.
+     * Omit to return all categories.
+     *
+     * @example
+     * ```ts
+     * // All categories (no filters)
+     * {}
+     *
+     * // Categories matching "gym"
+     * { filters: ['gym'] }
+     *
+     * // Categories matching either "gym" or "italian restaurant"
+     * { filters: ['gym', 'italian restaurant'] }
+     * ```
+     */
+    filters?: string[];
+};
+
+/**
+ * Response from the POI categories service.
+ *
+ * @group POI Categories
+ */
+export declare type POICategoriesResponse = {
+    poiCategories: POICategoryResult[];
+};
+
+/**
+ * @ignore
+ */
+export declare type PoiCategoriesResponseAPI = {
+    poiCategories: PoiCategoryAPI[];
+};
+
+/**
+ * @ignore
+ */
+export declare type PoiCategoryAPI = {
+    id: number;
+    name: string;
+    childCategoryIds: number[];
+    synonyms: string[];
+};
+
+/**
+ * A single POI category entry returned by the POI categories service.
+ *
+ * @group POI Categories
+ */
+export declare type POICategoryResult = {
+    /**
+     * The standardized enum value identifying this category.
+     *
+     * Use this value in search `poiCategories` parameters to filter results by category,
+     * or to cross-reference with `Place.properties.poi.categories` on search results.
+     */
+    code: POICategory;
+    /**
+     * Codes of sub-categories that also matched the current filter result set.
+     *
+     * Only contains codes present in the filtered result set — not the full list of
+     * possible sub-categories — so you can understand the category hierarchy without
+     * additional lookups.
+     *
+     * Use these values directly in search `poiCategories` parameters.
+     */
+    childCategoryCodes: POICategory[];
+    /**
+     * Human-readable category name in the requested language.
+     */
+    name: string;
+    /**
+     * Alternative names and synonyms for this category in the requested language.
+     */
+    synonyms: string[];
+};
+
 /**
  * @ignore
  */
@@ -6494,15 +6866,13 @@ export declare class SDKServiceError extends SDKError {
  * ```typescript
  * // Free-text search near a location
  * const results = await search({
- *   key: 'your-api-key',
  *   query: 'pizza restaurant',
- *   at: [4.9041, 52.3676],  // Amsterdam
+ *   position: [4.9041, 52.3676],  // Amsterdam
  *   limit: 10
  * });
  *
  * // Search within a specific area
  * const areaResults = await search({
- *   key: 'your-api-key',
  *   query: 'coffee shop',
  *   geometries: [polygon],  // Search within this polygon
  *   limit: 20
@@ -6510,11 +6880,9 @@ export declare class SDKServiceError extends SDKError {
  *
  * // Category search
  * const restaurants = await search({
- *   key: 'your-api-key',
- *   query: 'restaurant',
- *   categorySet: [7315],  // Restaurant category
- *   at: [4.9041, 52.3676],
- *   radius: 5000  // Within 5km
+ *   poiCategories: ['ITALIAN_RESTAURANT'],
+ *   position: [4.9041, 52.3676],
+ *   radiusMeters: 5000  // Within 5km
  * });
  * ```
  *
@@ -6972,6 +7340,26 @@ declare type SummaryAPI_2 = Omit<RouteSummary & LegSummary, 'arrivalTime' | 'dep
  */
 declare type SummaryQueryType = 'NEARBY' | 'NON_NEAR';
 
+/**
+ * @ignore
+ */
+declare type TiledEntryAPI = MetricsAPI & {
+    lat: number;
+    lon: number;
+};
+
+/**
+ * @ignore
+ */
+declare type TimedEntryAPI = MetricsAPI & {
+    date?: string;
+    year?: number;
+    month?: number;
+    week?: number;
+    hour?: number;
+    day?: number;
+};
+
 /**
  * @ignore
  */
@@ -7007,6 +7395,231 @@ declare type TimeRangeAPI = {
  */
 export declare type TimeZoneRequest = 'iana';
 
+/**
+ * Run a synchronous traffic area analytics report for a polygon region.
+ *
+ * Submits a single Polygon region with a date range and requested metrics, and
+ * receives the full analysis result immediately (no polling required).
+ *
+ * @remarks
+ * **Lite report constraints:**
+ * - Only a single region (Polygon Feature) may be submitted per request.
+ * - The date range (`startDate` → `endDate`) must not exceed 31 days.
+ *
+ * **Key data returned per region:**
+ * - `baseData`: overall aggregated metrics for the full analysis period
+ * - `timedData`: time-series breakdown at yearly / monthly / weekly / daily / hourly granularity
+ * - `tiledData`: per-tile heatmap metrics (when available)
+ * - `anomalies`: detected traffic anomalies keyed by data type
+ *
+ * **Available metrics (`dataTypes`):**
+ * - `SPEED` — average speed on the road network (km/h)
+ * - `FREE_FLOW_SPEED` — average speed under uncongested conditions (km/h)
+ * - `CONGESTION_LEVEL` — percentage increase in travel time above free-flow
+ * - `TRAVEL_TIME` — average travel time per 10 km (minutes)
+ * - `NETWORK_LENGTH` — total length of road segments with data (meters)
+ *
+ * @param params - Traffic Area Analytics parameters
+ * @param customTemplate - Advanced customization for request/response handling
+ *
+ * @returns Promise resolving to a {@link TrafficAreaAnalytics} FeatureCollection
+ *
+ * @example
+ * ```typescript
+ * // Basic speed and congestion analysis for Amsterdam
+ * const result = await trafficAreaAnalytics({
+ *   startDate: new Date('2024-08-06'),
+ *   endDate: new Date('2024-08-06'),
+ *   functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD', 'LOCAL_CONNECTING_ROAD', 'LOCAL_ROAD_HIGH_IMPORTANCE'],
+ *   hours: [7, 8, 9, 17, 18],
+ *   dataTypes: ['SPEED', 'CONGESTION_LEVEL'],
+ *   geometry: {
+ *     type: 'Polygon',
+ *     coordinates: [
+ *       [[4.896128, 52.382402], [4.875701, 52.368459], [4.923611, 52.36341], [4.896128, 52.382402]]
+ *     ]
+ *   }
+ * });
+ *
+ * const region = result.features[0];
+ * console.log(region.properties.baseData.speed);         // avg speed (km/h)
+ * console.log(region.properties.baseData.congestionLevel); // congestion %
+ * console.log(region.properties.timedData.hourly);       // hourly breakdown
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Full metrics over a multi-day period
+ * const result = await trafficAreaAnalytics({
+ *   startDate: new Date('2024-08-01'),
+ *   endDate: new Date('2024-08-07'),
+ *   functionalRoadClasses: 'all',
+ *   hours: 'all',
+ *   dataTypes: ['SPEED', 'FREE_FLOW_SPEED', 'CONGESTION_LEVEL', 'TRAVEL_TIME', 'NETWORK_LENGTH'],
+ *   geometry: {
+ *     type: 'Polygon',
+ *     coordinates: [[[4.89, 52.37], [4.91, 52.37], [4.91, 52.39], [4.89, 52.39], [4.89, 52.37]]]
+ *   }
+ * });
+ *
+ * result.features[0].properties.timedData.daily?.forEach(day => {
+ *   console.log(day.date, day.congestionLevel);
+ * });
+ * ```
+ *
+ * @see [Area Analytics API Documentation](https://developer.tomtom.com/area-analytics/documentation/api/analysis-lite)
+ *
+ * @group Traffic
+ */
+export declare const trafficAreaAnalytics: (params: TrafficAreaAnalyticsParams, customTemplate?: Partial<TrafficAreaAnalyticsTemplate>) => Promise<TrafficAreaAnalytics>;
+
+/**
+ * @ignore
+ */
+declare type TrafficAreaAnalyticsBaseParams = {
+    /**
+     * Optional name for the analysis report.
+     */
+    name?: string;
+    /**
+     * Traffic metrics to include in the analysis.
+     *
+     * @remarks
+     * At least one data type must be provided.
+     *
+     * @example ['SPEED', 'CONGESTION_LEVEL', 'FREE_FLOW_SPEED']
+     */
+    dataTypes: AreaAnalyticsDataType[];
+    /**
+     * Functional road classes to include in the analysis, or `'all'` to include every class.
+     *
+     * @remarks
+     * At least one value must be provided, or pass `'all'` as a shorthand for all nine classes.
+     *
+     * @example ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD']
+     * @example 'all'
+     */
+    functionalRoadClasses: FunctionalRoadClass[] | 'all';
+    /**
+     * Hours of the day to include in the analysis (0–23), or `'all'` to include every hour.
+     *
+     * @remarks
+     * Provide at least one hour, or pass `'all'` as a shorthand for `[0, 1, 2, ..., 23]`.
+     *
+     * @example [7, 8, 9, 17, 18]
+     * @example 'all'
+     */
+    hours: number[] | 'all';
+    /**
+     * The GeoJSON Polygon or MultiPolygon geometry defining the analysis region.
+     *
+     * @remarks
+     * The lite endpoint accepts exactly one region. For multi-region analysis,
+     * use the standard (async) report creation endpoint.
+     */
+    geometry: Polygon | MultiPolygon;
+};
+
+/**
+ * Continuous date-range variant: analyse traffic between `startDate` and `endDate`.
+ *
+ * - `endDate` is optional; when omitted it defaults to **today**.
+ * - The range must not exceed **31 days**.
+ * - Mutually exclusive with {@link TrafficAreaAnalyticsDays}.
+ *
+ * @group Traffic
+ */
+export declare type TrafficAreaAnalyticsDateRange = {
+    /**
+     * Start date of the analysis period.
+     * Accepts a `Date` object or an ISO `'YYYY-MM-DD'` string.
+     *
+     * @example '2024-08-01'
+     * @example new Date('2024-08-01')
+     */
+    startDate: AreaAnalyticsDateInput;
+    /**
+     * End date of the analysis period (inclusive).
+     * Accepts a `Date` object or an ISO `'YYYY-MM-DD'` string.
+     * When omitted, defaults to **today**.
+     *
+     * @remarks Must be within 31 days from `startDate`.
+     *
+     * @example '2024-08-07'
+     * @example new Date('2024-08-07')
+     */
+    endDate?: AreaAnalyticsDateInput;
+    days?: never;
+};
+
+/**
+ * Specific-dates variant: analyse traffic on an explicit list of dates.
+ *
+ * Useful for non-consecutive dates such as "all Mondays in August".
+ * Mutually exclusive with {@link TrafficAreaAnalyticsDateRange}.
+ *
+ * @group Traffic
+ */
+export declare type TrafficAreaAnalyticsDays = {
+    /**
+     * List of specific dates to include in the analysis.
+     * Accepts `Date` objects or ISO `'YYYY-MM-DD'` strings.
+     *
+     * @example ['2024-08-05', '2024-08-12', '2024-08-19', '2024-08-26']
+     */
+    days: AreaAnalyticsDateInput[];
+    startDate?: never;
+    endDate?: never;
+};
+
+/**
+ * Parameters for the Traffic Area Analytics Lite service.
+ *
+ * @remarks
+ * Supply **either** `startDate` (+ optional `endDate`) **or** `days` — these
+ * two options are mutually exclusive.
+ *
+ * The lite endpoint runs analysis synchronously and returns results immediately,
+ * with the constraint that the date range must not exceed 31 days and only a
+ * single region may be submitted.
+ *
+ * @example
+ * ```typescript
+ * // Continuous range — endDate defaults to today when omitted
+ * const result = await trafficAreaAnalytics({
+ *   startDate: '2024-08-01',
+ *   functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD', 'LOCAL_CONNECTING_ROAD', 'LOCAL_ROAD_HIGH_IMPORTANCE'],
+ *   hours: [7, 8, 9, 17, 18],
+ *   dataTypes: ['SPEED', 'CONGESTION_LEVEL'],
+ *   geometry: {
+ *     type: 'Polygon',
+ *     coordinates: [[[4.896128, 52.382402], [4.875701, 52.368459], [4.923611, 52.36341], [4.896128, 52.382402]]]
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Specific dates
+ * const result = await trafficAreaAnalytics({
+ *   days: ['2024-08-05', '2024-08-12', '2024-08-19', '2024-08-26'],
+ *   functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD'],
+ *   hours: [8, 9, 17, 18],
+ *   dataTypes: ['SPEED'],
+ *   geometry: polygon
+ * });
+ * ```
+ *
+ * @group Traffic
+ */
+export declare type TrafficAreaAnalyticsParams = CommonServiceParams & TrafficAreaAnalyticsBaseParams & (TrafficAreaAnalyticsDateRange | TrafficAreaAnalyticsDays);
+
+/**
+ * Traffic Area Analytics service template type.
+ * @ignore
+ */
+declare type TrafficAreaAnalyticsTemplate = ServiceTemplate<TrafficAreaAnalyticsParams, FetchInput<AreaAnalyticsRequestBody>, AreaAnalyticsResponseAPI, TrafficAreaAnalytics>;
+
 /**
  * @ignore
  */