{ "openapi": "3.1.0", "info": { "title": "TerraMap API", "description": "Maps & Location Infrastructure.\n\nThis reference documents the **TerraMap service APIs** - the\nendpoints an application calls. Authenticate every one of them\nwith an API key:\n\n Authorization: Bearer tm_pk_... (publishable, for browsers\n and mobile apps)\n Authorization: Bearer tm_sk_... (secret, server-side only)\n\nA publishable key is meant to be visible in client code and is\nrestricted by origin, IP or app identity. A secret key never\nbelongs in a browser.\n\nAccounts, keys, credits and usage are managed at\n, not through this reference.\n\n**Place Search** (`/api/v1/search`) and **Reverse\nGeocoding** (`/api/v1/geocode/reverse`) are real, over\n3,074,320 Austrian places.\n\nThe remaining service endpoints - routing, matrix, TSP, VRP,\nsnap-to-road and navigation - are still **mocks**, and each\none says so in its own summary. They run the complete\nauthentication, authorization, restriction, credit and\nmetering pipeline and return `mock: true` with no real\nresult. Nothing here fabricates geometry.\n\nCoverage is **Austria** only.\n", "version": "v1" }, "servers": [ { "url": "https://api.terramap.at", "description": "TerraMap production" } ], "tags": [ { "name": "TerraMap services (mock)", "description": "Mocks that exercise the full security and metering pipeline. Search and reverse geocoding are no longer here - they are real (see Search & Geocoding)." }, { "name": "Search & Geocoding", "description": "Place search and reverse geocoding over the TerraMap place index (Austria)" } ], "paths": { "/api/v1/snap-to-road": { "post": { "tags": [ "TerraMap services (mock)" ], "summary": "Snap to road (mock)", "operationId": "snapToRoad", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/MockResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/routes": { "post": { "tags": [ "TerraMap services (mock)" ], "summary": "Routing (mock)", "operationId": "route", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/MockResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/optimization/vrp": { "post": { "tags": [ "TerraMap services (mock)" ], "summary": "Vehicle routing optimisation (mock)", "operationId": "vrp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VrpRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/MockResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/optimization/tsp": { "post": { "tags": [ "TerraMap services (mock)" ], "summary": "Travelling salesman optimisation (mock)", "operationId": "tsp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TspRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/MockResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/navigation/session": { "post": { "tags": [ "TerraMap services (mock)" ], "summary": "Start a navigation session (mock)", "operationId": "navigationSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavigationSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/MockResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/matrix": { "post": { "tags": [ "TerraMap services (mock)" ], "summary": "Distance/duration matrix (mock)", "description": "Billed per matrix element (origins x destinations), computed server-side.", "operationId": "matrix", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/MockResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/search": { "get": { "tags": [ "Search & Geocoding" ], "summary": "Place search", "description": "Searches names, alternative names, streets and cities across the TerraMap place index. Requires the SEARCH permission on the API key.", "operationId": "search", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "proximity", "in": "query", "description": "Bias results toward this point, as \"longitude,latitude\"", "required": false, "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "'de' (default) or 'en'. Reorders name field weighting only.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ApiResponseListPlace" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/geocode/reverse": { "get": { "tags": [ "Search & Geocoding" ], "summary": "Reverse geocoding", "description": "Returns the most meaningful local place at a coordinate — an address, building, POI or street. Never a city, district or other administrative area. Requires the REVERSE_GEOCODE permission.", "operationId": "reverseGeocode", "parameters": [ { "name": "lon", "in": "query", "description": "Longitude, -180..180", "required": true, "schema": { "type": "number", "format": "double" } }, { "name": "lat", "in": "query", "description": "Latitude, -90..90", "required": true, "schema": { "type": "number", "format": "double" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ApiResponseListPlace" } } } } }, "security": [ { "apiKey": [] } ] } } }, "components": { "schemas": { "Coordinate": { "type": "object", "properties": { "lon": { "type": "number", "format": "double" }, "lat": { "type": "number", "format": "double" } } }, "SnapRequest": { "type": "object", "properties": { "points": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } } } }, "MockResponse": { "type": "object", "properties": { "mock": { "type": "boolean" }, "service": { "type": "string", "enum": [ "MAP_TILES", "MAP_STYLES", "MAP_SESSION", "SEARCH", "REVERSE_GEOCODE", "ROUTING", "MATRIX", "TSP", "VRP", "SNAP_TO_ROAD", "NAVIGATION" ] }, "requestId": { "type": "string" }, "notice": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } } }, "RouteRequest": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/Coordinate" }, "destination": { "$ref": "#/components/schemas/Coordinate" }, "waypoints": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } } } }, "VrpRequest": { "type": "object", "properties": { "stops": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } }, "vehicles": { "type": "integer", "format": "int32" } } }, "TspRequest": { "type": "object", "properties": { "stops": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } } } }, "NavigationSessionRequest": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/Coordinate" }, "destination": { "$ref": "#/components/schemas/Coordinate" } } }, "MatrixRequest": { "type": "object", "properties": { "origins": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } }, "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } } } }, "ApiResponseListPlace": { "type": "object", "properties": { "status": { "type": "integer", "format": "int32" }, "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } } } }, "Place": { "type": "object", "properties": { "name": { "type": "string" }, "nameEn": { "type": "string" }, "type": { "type": "string" }, "subType": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "district": { "type": "string" }, "postCode": { "type": "string" }, "street": { "type": "string" }, "houseNumber": { "type": "string" }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "weight": { "type": "integer", "format": "int32" } } } }, "securitySchemes": { "apiKey": { "type": "http", "description": "Authorization: Bearer tm_pk_... or tm_sk_...", "scheme": "bearer" } } } }