{ "openapi": "3.0.3", "info": { "title": "Vector Tile API v2", "description": "The Vector Tile API allows you to request tiles containing vector data using content from the HERE platform. Our vector tiles use Web Mercator projection and follow the Vector Tile Specification. This format contains geometries, such as points and lines, that define polygons, labels, such as road names or city names, and other kinds of data that are typically passed to a renderer to draw a map. The tiles are optimized to be visualized as 512 screen pixels per tile. The Vector Tile API supports the standard [HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4)\n\n## CORS Support\n\nThe server supports [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing).\nThe following headers are included in every response.\n\n```http\n\nAccess-Control-Allow-Headers: Authorization, Origin, Referer, User-Agent, If-None-Match\n\nAccess-Control-Allow-Methods: GET, OPTIONS\n\nAccess-Control-Allow-Origin: *\n\n```\n ", "termsOfService": "http://developer.here.com/terms-conditions", "license": { "name": "HERE Documentation License", "url": "https://legal.here.com/en-gb/terms/documentation-license" }, "version": "2.4.2" }, "servers": [ { "url": "https://vector.hereapi.com/v2", "description": "Production" } ], "paths": { "/health": { "get": { "tags": [ "API Information" ], "summary": "Vector Tile Service basic health check endpoint", "description": "Used to check the basic health status of the service", "operationId": "getHealth", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK returned, service is Ok.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } } } }, "security": [ {} ] } }, "/openapi": { "get": { "tags": [ "API Information" ], "summary": "Returns open api specifications of v2. By default output format is json. Set request header 'accept = application/x-yaml' to get in yaml format.", "description": "Returns open api specifications of v2. By default output format is json. Set request header 'accept = application/x-yaml' to get in yaml format.", "operationId": "getOpenapi", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Returns api specifications of a particular version.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ {} ] } }, "/vectortiles/copyright": { "get": { "tags": [ "Metadata" ], "summary": "Returns the copyright", "description": "Returns the copyright", "operationId": "getCopyright", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Information about the copyright.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyrightsSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/vectortiles/docs/layers/json": { "get": { "tags": [ "Metadata" ], "summary": "Returns OMV-2 layers documentation.", "description": "Returns OMV-2 layers documentation.", "operationId": "getDocs", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Documentation returned.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } } } }, "security": [ {} ] } }, "/vectortiles/info": { "get": { "tags": [ "Metadata" ], "summary": "Returns the map version. This version is valid only for 24h", "description": "Returns the map version. This version is valid only for 24h", "operationId": "getInfo", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Information about the catalog and map version returned.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/vectortiles/languages": { "get": { "tags": [ "Metadata" ], "summary": "Returns the map languages.", "description": "Returns the list of available map languages per map variant.", "operationId": "getLanguages", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - List of languages per map variant.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguagesSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/vectortiles/politicalViews": { "get": { "tags": [ "Metadata" ], "summary": "Returns the political views.", "description": "Returns the list of available political views.", "operationId": "getPoliticalViews", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - List of political views.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoliticalViewsSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/vectortiles/proto": { "get": { "tags": [ "Metadata" ], "summary": "Returns a list of available protocol buffer formats.", "description": "Returns a list of available protocol buffer formats.", "operationId": "listProto", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Protocol buffer format list retrieved.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtoSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/vectortiles/proto/{name}": { "get": { "tags": [ "Metadata" ], "summary": "Returns the specified protocol buffer file format.", "description": "Returns the specified protocol buffer file format.", "operationId": "getProto", "parameters": [ { "name": "name", "in": "path", "description": "Protobuf file name", "required": true, "schema": { "type": "string", "description": "Specifies the name of the requested protocol buffer format file.", "example": "vector_tile.proto" } }, { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Protocol buffer format file retrieved.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Requested protocol buffer format file is not available.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/vectortiles/pviews": { "get": { "tags": [ "Metadata" ], "summary": "Returns the political views.", "description": "Returns the list of available political views.", "operationId": "getPviews", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - List of political views.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoliticalViewsSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } }, "deprecated": true } }, "/vectortiles/{map}/{projection}/{z}/{x}/{y}/{format}": { "get": { "tags": [ "Data" ], "summary": "Retrieves the protocol buffer encoded binary tile.", "description": "Retrieves the protocol buffer encoded binary tile.", "operationId": "getTile", "parameters": [ { "name": "map", "in": "path", "description": "Specifies the map variants available for the tile. The access to each map is determined by the contract of the user.\n* base - includes base map\n* core - includes everything form `base` and additional data for some countries (for example: Japan)", "required": true, "schema": { "type": "string", "enum": [ "base", "core" ], "example": "base" } }, { "name": "projection", "in": "path", "description": "Specifies the tile projection.\n* mc - Mercator Projection", "required": true, "schema": { "type": "string", "enum": [ "mc" ], "example": "mc" } }, { "name": "z", "in": "path", "description": "Specifies the tile Zoom level. Accepted values range from 0-17.\n* minimum - 0\n* maximum - 17", "required": true, "schema": { "type": "integer", "example": 11, "maximum": 17, "minimum": 0 } }, { "name": "x", "in": "path", "description": "Specifies the X coordinate index. This parameter is dependent upon the tile Zoom level.\n* minimum - 0\n* maximum - 2^z-1 (depends on the Zoom level)", "required": true, "schema": { "type": "integer", "example": 1100, "minimum": 0 } }, { "name": "y", "in": "path", "description": "Specifies the Y coordinate index. This parameter is dependent upon the tile Zoom level.\n* minimum - 0\n* maximum - 2^z-1 (depends on the Zoom level)", "required": true, "schema": { "type": "integer", "example": 671, "minimum": 0 } }, { "name": "format", "in": "path", "description": "Specifies the tile format.\n* omv - Optimized Map for Visualization (follows Map Vector Tile open specification)", "required": true, "schema": { "type": "string", "enum": [ "omv" ], "example": "omv" } }, { "name": "mv", "in": "query", "description": "Specifies the map version to be used. The map version can be retrieved by querying /info", "required": false, "deprecated": true, "schema": { "type": "string" } }, { "name": "content", "in": "query", "description": "A comma-separated list of content to include in the tile. The available content identifiers are:\n* `default`: Default map content.\n* `advanced_pois`: Advanced Points of interest layer.\n* `advanced_roads`: Advanced Roads layer.\n* `contours`: Contours layer.\n* `hillshade`: Hillshade layer.\n* `road_labels`: The `road_labels` layer.\n* `transit`: Transit layer.", "required": false, "schema": { "type": "string", "description": "Comma-separated list of content identifiers", "default": "default", "example": "default,advanced_pois,advanced_roads", "pattern": "^[\\w\\d_-]+(?:,[\\w\\d_-]+)*$" } }, { "name": "datasets", "in": "query", "description": "Specifies a comma-separated list of layer names to exclude from the resulting map vector tile.
\nThe list must have the following format: (-LAYER_1,-LAYER_2,...), Examples:\n* (-roads) to remove just roads,\n* (-roads,-water,-buildings) to remove roads, water areas and buildings", "required": false, "schema": { "type": "string", "example": "singleValue:\n value: (-roads)\n summary: '?datasets=(-roads)'\nmultipleValues:\n value: '(-roads,-water,-buildings)'\n summary: '?datasets=(-roads,-water,-buildings)'" } }, { "name": "if-none-match", "in": "header", "description": "Specifies an optional entity tag of the resource cached in the client.", "required": false, "schema": { "type": "string", "example": "12345" } }, { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Binary tile successfully retrieved.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Entity tag. Version of the provided tile." }, "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/x-protobuf": { "schema": { "type": "string", "format": "binary" } } } }, "204": { "description": "Tile data is not available in data (at all or for requested tile version) or no features in requested tile.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } } }, "304": { "description": "The resource cached in the client (identified by the if-none-match) header has not changed.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } } }, "400": { "description": "Possible messages due to request URI validation error:\n* Map 'some' is invalid.\n* Format 'wrong' format is invalid. Accepted formats are - omv.\n* Projection 'na' is invalid. Accepted projection are - mc.\n* Zoom level 100 is invalid. Accepted zoom levels are - [1-17].", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/version": { "get": { "tags": [ "API Information" ], "summary": "Returns various version information.", "description": "Returns various version information.", "operationId": "getVersion", "parameters": [ { "name": "X-Request-ID", "in": "header", "description": "Request id.", "required": false, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "OK - Various version information returned.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionSchema" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } } }, "components": { "schemas": { "Copyright": { "type": "object", "required": [ "boxes", "minLevel", "maxLevel", "label", "alt" ], "properties": { "alt": { "type": "string", "description": "Verbose copyright text of the label to display by mouse over label or info menu entry.", "example": "copyright IGN 2009 - BD TOPO" }, "boxes": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "float", "description": "The bounding boxes define areas where specific copyrights are valid. A bounding box is defined by `bottom` (latitude), `left` (longitude) and `top` (latitude), `right` (longitude)." }, "example": [ 15.6985, -61.9309, 16.5953, -61.0013 ], "maxItems": 4, "minItems": 4 } }, "label": { "type": "string", "description": "Copyright text to display after the copyright symbol on the map.", "example": "IGN" }, "maxLevel": { "type": "integer", "description": "Maximum zoom level for the specified copyright label.", "example": "20" }, "minLevel": { "type": "integer", "description": "Minimum zoom level for the specified copyright label.", "example": "11" } } }, "CopyrightsSchema": { "type": "object", "required": [ "base", "core" ], "properties": { "base": { "type": "array", "items": { "$ref": "#/components/schemas/Copyright" } }, "core": { "type": "array", "items": { "$ref": "#/components/schemas/Copyright" } } } }, "DataVersionSchema": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string", "description": "Current api version.", "example": "2.4.2" }, "version": { "type": "string", "description": "The current encoded map version. Lasts for 24 hours. After that period, this value should be refreshed.", "example": "in337jp128" } } }, "ErrorSchema": { "type": "object", "required": [ "action", "cause", "code", "correlationId", "status", "title" ], "properties": { "action": { "type": "string", "description": "Actionable instructions for the API consumer.", "example": "Correct input data and retry request." }, "cause": { "type": "string", "description": "The cause of the error.", "example": "The input data in question does not meet validation rules." }, "code": { "type": "string", "description": "Service specific error code.", "example": "E202101" }, "correlationId": { "type": "string", "description": "Trace ID associated with this request, for future use.", "example": "4199533b-6290-41db-8d79-edf4f4019a74" }, "status": { "type": "integer", "description": "HTTP Status Code", "example": 400 }, "title": { "type": "string", "description": "Error message.", "example": "Input data failed validation." } } }, "InfoSchema": { "type": "object", "required": [ "mapVersion", "softwareVersion" ], "properties": { "mapVersion": { "type": "string", "description": "The current encoded map version. Lasts for 24 hours. After that period, this value should be refreshed.", "example": "in337jp128" }, "softwareVersion": { "type": "string", "description": "The version of HERE Vector Tiles Service.", "example": "1.1.274" } } }, "LanguagesSchema": { "type": "object", "required": [ "base", "core" ], "properties": { "base": { "type": "array", "items": { "type": "string", "description": "Indicates which languages the map supports on this variant." }, "example": [ "ar", "as", "az", "be" ] }, "core": { "type": "array", "items": { "type": "string", "description": "Indicates which languages the map supports on this variant." }, "example": [ "ar", "as", "az", "be" ] } } }, "PoliticalViewsSchema": { "type": "object", "required": [ "base", "core" ], "properties": { "base": { "type": "array", "items": { "type": "string", "description": "Indicates which country has disputed territories." }, "example": [ "ab", "ar", "cy", "eg" ] }, "core": { "type": "array", "items": { "type": "string", "description": "Indicates which country has disputed territories." }, "example": [ "ab", "ar", "cy", "eg" ] } } }, "ProtoItemSchema": { "type": "object", "required": [ "name", "description" ], "properties": { "description": { "type": "string", "description": "A textual description of the format.", "example": "OMV format" }, "name": { "type": "string", "description": "The name of the file to be retrieved in a subsequent call.", "example": "vector_tile.proto" } } }, "ProtoSchema": { "type": "object", "required": [ "schemas" ], "properties": { "schemas": { "type": "array", "items": { "$ref": "#/components/schemas/ProtoItemSchema" } } } }, "VersionSchema": { "type": "object", "required": [ "apiVersion", "dataVersions", "serviceVersion" ], "properties": { "apiVersion": { "type": "string", "description": "Current api version.", "example": "2.4.2" }, "dataVersions": { "type": "array", "items": { "$ref": "#/components/schemas/DataVersionSchema" } }, "serviceVersion": { "type": "string", "description": "The version of HERE Vector Tiles Service.", "example": "1.1.274" } } } }, "responses": { "UnauthorizedError": { "description": "Access token is missing or invalid.", "headers": { "x-correlation-id": { "schema": { "type": "string" }, "description": "End to end correlation id." }, "x-request-id": { "schema": { "type": "string" }, "description": "HTTP request id." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "error_description" ], "properties": { "error": { "type": "string", "enum": [ "Unauthorized" ] }, "error_description": { "type": "string", "description": "Access is denied due to invalid credentials." } } } } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "A key generated specifically to authenticate API requests. For more information on how to get an API key, see [Identity & Access Management - API keys](https://docs.here.com/identity-and-access-management/docs/plat-using-apikeys)." }, "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request. For more information on how to get a bearer token, see [Identity & Access Management - OAuth tokens](https://docs.here.com/identity-and-access-management/docs/how-to-authorize-with-oauth-20)." } } }, "security": [ { "ApiKey": [] }, { "Bearer": [] } ], "externalDocs": { "url": "https://docs.here.com/map-rendering/docs/introduction-vector-tile-api", "description": "The Developer guide and Changelog are available here." } }