openapi: 3.0.0
info:
contact:
x-twitter: TomTom
description: "The Maps API web services suite offers the following APIs:\n - Raster\n The Maps Raster API renders map data that is divided into gridded sections called tiles. Tiles are square images (png or jpg format) in various sizes which are available at 19 different zoom levels, ranging from 0 to 20. For zoom level 0, the entire earth is displayed on one single tile, while at zoom level 20, the world is divided into 2<sup>40</sup> tiles.\n - Vector\n Similar to Maps Raster API, the Maps Vector API serves data on different zoom level ranging from 0 to 22. For zoom level 0, the entire earth is displayed on one single tile, while at zoom level 22, the world is divided into 2<sup>44</sup> tiles.\n The Maps Vector Service delivers geographic map data packaged in a vector representation of squared sections called vector tiles. Each tile includes pre-defined collections of map features (points, lines, road shapes, water polygons, building footprints, ect.) delivered in one of the specified vector formats. Format of the tile is formally described using protobuf schema."
title: Maps Additional Data Search API
version: '3.0'
x-apisguru-categories:
- location
x-logo:
url: https://twitter.com/TomTom/profile_image?size=original
x-origin:
- converter:
url: https://github.com/lucybot/api-spec-converter
format: openapi
url: https://developer.tomtom.com/system/files/swagger_models/maps_api_0.yaml
x-providerName: tomtom.com
x-serviceName: maps
servers:
- url: https://api.tomtom.com
security:
- api_key: []
tags:
- name: Search
paths:
/search/{versionNumber}/cS/{category}.{ext}:
get:
deprecated: true
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: pizza
in: path
name: category
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- $ref: '#/components/parameters/typeahead'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/ofs'
- $ref: '#/components/parameters/countrySet'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/topLeft'
- $ref: '#/components/parameters/btmRight'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/idxSet'
- $ref: '#/components/parameters/view'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Low Bandwith Category Search
tags:
- Search
/search/{versionNumber}/categorySearch/{query}.{ext}:
get:
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: pizza
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- $ref: '#/components/parameters/typeahead'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/ofs'
- $ref: '#/components/parameters/countrySet'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/topLeft'
- $ref: '#/components/parameters/btmRight'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/extendedPostalCodesFor'
- $ref: '#/components/parameters/view'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Category Search
tags:
- Search
/search/{versionNumber}/geometrySearch/{query}.{ext}:
get:
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: pizza
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- description: List of geometries to filter by. Available types are CIRCLE (with the radius expressed in meters) and POLYGON.
example: '[{"type":"POLYGON", "vertices":["37.7524152343544, -122.43576049804686", "37.70660472542312, -122.43301391601562", "37.712059855877314, -122.36434936523438", "37.75350561243041, -122.37396240234374"]}, {"type":"CIRCLE", "position":"37.71205, -121.36434", "radius":6000}, {"type":"CIRCLE", "position":"37.31205, -121.36434", "radius":1000}]'
in: query
name: geometryList
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/extendedPostalCodesFor'
- $ref: '#/components/parameters/idxSet'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Geometry Search
tags:
- Search
post:
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: pizza
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/extendedPostalCodesFor'
- $ref: '#/components/parameters/idxSet'
requestBody:
content:
application/json:
schema:
example:
geometryList:
- type: POLYGON
vertices:
- 37.7524152343544,-122.43576049804686
- 37.70660472542312,-122.43301391601562
- 37.712059855877314,-122.36434936523438
- 37.75350561243041,-122.37396240234374
- position: 37.71205,-121.36434
radius: 6000
type: CIRCLE
- position: 37.31205,-121.36434
radius: 1000
type: CIRCLE
properties:
geometryList:
items:
properties:
position:
type: string
radius:
type: integer
type:
type: string
vertices:
items:
type: string
type: array
type: object
type: array
type: object
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Geometry Search
tags:
- Search
/search/{versionNumber}/nearbySearch/.{ext}:
get:
parameters:
- $ref: '#/components/parameters/versionNumber'
- $ref: '#/components/parameters/ext'
- description: "Latitude where results should be biased. \nNOTE: supplying a lat/lon without a radius will return search results biased to that point."
example: 37.337
in: query
name: lat
required: true
schema:
format: float
type: number
- description: 'Longitude where results should be biased
NOTE: supplying a lat/lon without a radius will return search results biased to that point.'
example: -121.89
in: query
name: lon
required: true
schema:
format: float
type: number
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/ofs'
- $ref: '#/components/parameters/countrySet'
- description: If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters.
in: query
name: radius
schema:
default: 10000
maximum: 50000
type: integer
- deprecated: true
description: Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon.
example: 37.553,-122.453
in: query
name: topLeft
schema:
type: string
- deprecated: true
description: Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon.
example: 37.4,-122.55
in: query
name: btmRight
schema:
type: string
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/extendedPostalCodesFor'
- $ref: '#/components/parameters/minFuzzyLevel'
- $ref: '#/components/parameters/maxFuzzyLevel'
- $ref: '#/components/parameters/idxSet'
- $ref: '#/components/parameters/view'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Nearby Search
tags:
- Search
/search/{versionNumber}/poiSearch/{query}.{ext}:
get:
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: pizza
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- $ref: '#/components/parameters/typeahead'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/ofs'
- $ref: '#/components/parameters/countrySet'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/topLeft'
- $ref: '#/components/parameters/btmRight'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/extendedPostalCodesFor'
- $ref: '#/components/parameters/view'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Points of Interest Search
tags:
- Search
/search/{versionNumber}/routedSearch/{query}/{position}/{heading}.{ext}:
get:
deprecated: true
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: gas
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/position'
- description: The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north (so north is 0, east is 90, etc.)
example: 90
in: path
name: heading
required: true
schema:
format: float
type: number
- $ref: '#/components/parameters/ext'
- $ref: '#/components/parameters/typeahead'
- $ref: '#/components/parameters/limit'
- description: Multiplies the limit by N to gather more candidate POIs, which will then be sorted by drive distance, returning only the top candidates according to the limit.
in: query
name: multiplier
schema:
default: 2
type: integer
- $ref: '#/components/parameters/routingTimeout'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/extendedPostalCodesFor'
- $ref: '#/components/parameters/idxSet'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Routed Search
tags:
- Search
/search/{versionNumber}/s/{query}.{ext}:
get:
deprecated: true
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: pizza
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- $ref: '#/components/parameters/typeahead'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/ofs'
- $ref: '#/components/parameters/countrySet'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/topLeft'
- $ref: '#/components/parameters/btmRight'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/idxSet'
- $ref: '#/components/parameters/view'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Low Bandwith Search
tags:
- Search
/search/{versionNumber}/search/{query}.{ext}:
get:
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: 'Query string. Must be properly URL encoded.
To perform a reverse geocode, the user can provide latitude and longitude coordinates directly in the query. More information can be found <a href="/search-api/search-api-documentation-search/fuzzy-search#AdditionalInfo">here</a>.'
example: pizza
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- $ref: '#/components/parameters/typeahead'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/ofs'
- $ref: '#/components/parameters/countrySet'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/topLeft'
- $ref: '#/components/parameters/btmRight'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/extendedPostalCodesFor'
- $ref: '#/components/parameters/minFuzzyLevel'
- $ref: '#/components/parameters/maxFuzzyLevel'
- $ref: '#/components/parameters/idxSet'
- $ref: '#/components/parameters/view'
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Fuzzy Search
tags:
- Search
/search/{versionNumber}/searchAlongRoute/{query}.{ext}:
post:
parameters:
- $ref: '#/components/parameters/versionNumber'
- description: Query string. Must be properly URL encoded.
example: pizza
in: path
name: query
required: true
schema:
type: string
- $ref: '#/components/parameters/ext'
- description: Maximum detour time
example: 1200
in: query
name: maxDetourTime
required: true
schema:
maximum: 3600
type: integer
- $ref: '#/components/parameters/limit'
requestBody:
content:
application/json:
schema:
example:
route:
points:
- lat: 37.7524152343544
lon: -122.43576049804686
- lat: 37.70660472542312
lon: -122.43301391601562
- lat: 37.712059855877314
lon: -122.36434936523438
- lat: 37.75350561243041
lon: -122.37396240234374
properties:
route:
properties:
points:
items:
properties:
lat:
format: float
type: number
lon:
format: float
type: number
type: object
type: array
type: object
type: object
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
404/596:
$ref: '#/components/responses/404596'
5XX:
$ref: '#/components/responses/5xx'
summary: Along Route Search
tags:
- Search
components:
parameters:
ofs:
description: Starting offset of the returned results within the full result set.
in: query
name: ofs
schema:
default: 0
maximum: 1900
type: integer
language:
description: Language in which search results should be returned. Should be one of <a href="/search-api/search-api-documentation/supported-languages">supported IETF language tags</a>, case insensitive.
in: query
name: language
schema:
type: string
extendedPostalCodesFor:
description: "Indexes for which extended postal codes should be included in the results. Available indexes are:\n - <b>Addr</b> = Address ranges\n - <b>Geo</b> = Geographies\n - <b>PAD</b> = Point Addresses\n - <b>POI</b> = Points of Interest\n - <b>Str</b> = Streets\n - <b>XStr</b> = Cross Streets (intersections)"
in: query
name: extendedPostalCodesFor
schema:
type: string
topLeft:
description: Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon.
example: 37.553,-122.453
in: query
name: topLeft
schema:
type: string
routingTimeout:
description: Only return results that arrive from routing engine within this time limit.
in: query
name: routingTimeout
schema:
default: 4000
type: integer
position:
description: This is specified as a comma separated string composed of lat., lon.
example: 37.8328,-122.27669
in: path
name: position
required: true
schema:
type: string
lat:
description: "Latitude where results should be biased. \nNOTE: supplying a lat/lon without a radius will return search results biased to that point."
example: 37.337
in: query
name: lat
schema:
format: float
type: number
ext:
description: Expected response format.
example: xml
in: path
name: ext
required: true
schema:
enum:
- json
- jsonp
- js
- xml
type: string
lon:
description: 'Longitude where results should be biased
NOTE: supplying a lat/lon without a radius will return search results biased to that point.'
example: -121.89
in: query
name: lon
schema:
format: float
type: number
limit:
description: Maximum number of search results that will be returned.
in: query
name: limit
schema:
default: 10
maximum: 100
type: integer
btmRight:
description: Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon.
example: 37.4,-122.55
in: query
name: btmRight
schema:
type: string
minFuzzyLevel:
description: Minimum fuzziness level to be used.
in: query
name: minFuzzyLevel
schema:
default: 1
maximum: 4
minimum: 1
type: integer
radius:
description: If radius <b>and</b> position are set, the results will be constrained to the defined area. The radius parameter is specified in meters.
in: query
name: radius
schema:
type: integer
countrySet:
description: Comma separated string of country codes. This will limit the search to the specified countries.
example: FR
in: query
name: countrySet
schema:
type: string
versionNumber:
description: Service version number. The current value is 2.
in: path
name: versionNumber
required: true
schema:
enum:
- 2
type: integer
maxFuzzyLevel:
description: Maximum fuzziness level to be used.
in: query
name: maxFuzzyLevel
schema:
default: 2
maximum: 4
minimum: 1
type: integer
view:
description: Geopolitical View.
in: query
name: view
required: false
schema:
default: Unified
enum:
- Unified
- IN
- PK
- IL
- MA
type: string
typeahead:
description: If the "typeahead" flag is set, the query will be interpreted as a partial input and the search will enter <b>predictive</b> mode.
in: query
name: typeahead
schema:
default: false
type: boolean
idxSet:
description: "A comma separated list of indexes which should be utilized for the search. Item order does not matter. Available indexes are:\n - <b>Addr</b> = Address range interpolation (when there is no PAD)\n - <b>Geo</b> = Geographies\n - <b>PAD</b> = Point Addresses\n - <b>POI</b> = Points of interest\n - <b>Str</b> = Streets\n - <b>Xstr</b> = Cross Streets (intersections)"
example: POI
in: query
name: idxSet
schema:
type: string
responses:
'404596':
description: 'Not Found: the HTTP request method (GET, POST, etc) or path is incorrect.'
'403':
description: "Forbidden: possible causes include:\n - Service requires SSL\n - Not authorized\n - Rate or volume limit exceeded\n - Unknown referer"
'405':
description: 'Method Not Allowed: the HTTP method (GET, POST, etc) is not supported for this request.'
5xx:
description: An error occurred while processing the request. Please try again later.
'200':
description: 'OK: the search successfully returned zero or more results.'
'400':
description: 'Bad Request: one or more parameters were incorrectly specified.'
securitySchemes:
api_key:
in: query
name: key
type: apiKey