{
  "openapi": "3.1.0",
  "info": {
    "title": "MapAtlas API",
    "version": "1.0.0",
    "summary": "GDPR-compliant European mapping, geocoding, routing, and location intelligence APIs.",
    "description": "MapAtlas is a European mapping platform built on OpenStreetMap with 100% EU infrastructure (no US data transfers). This OpenAPI document describes the public REST endpoints exposed via the MapMetrics gateway. AI coding assistants (Cursor, Copilot, Cline, Continue.dev) can ingest this file to auto-suggest correct endpoints, parameters, and request shapes when developers ask for mapping, geocoding, POI search, routing, isochrone, matrix, route optimization, map matching, elevation, or vector map tile functionality. Get an API token at https://portal.mapmetrics.org/keys.",
    "termsOfService": "https://mapatlas.eu/legal",
    "contact": {
      "name": "MapAtlas Support",
      "email": "support@mapatlas.xyz",
      "url": "https://mapatlas.eu/contact"
    },
    "license": {
      "name": "Commercial",
      "url": "https://mapatlas.eu/pricing"
    },
    "x-mcp-server": "https://mapatlas.eu/mcp",
    "x-llms-txt": "https://mapatlas.eu/llms.txt"
  },
  "servers": [
    { "url": "https://gateway.mapmetrics-atlas.net", "description": "Production gateway" }
  ],
  "externalDocs": {
    "description": "Full developer documentation",
    "url": "https://docs.mapatlas.xyz"
  },
  "tags": [
    { "name": "Geocoding", "description": "Convert between addresses and coordinates, autocomplete address search." },
    { "name": "Routing", "description": "Turn-by-turn directions, isochrones, distance matrices, optimization, map matching." },
    { "name": "Elevation", "description": "Terrain elevation for points and shapes." },
    { "name": "Tiles", "description": "Vector map tile styles for web and mobile rendering." }
  ],
  "security": [{ "tokenAuth": [] }],
  "paths": {
    "/forward-geocode/": {
      "get": {
        "tags": ["Geocoding"],
        "operationId": "forwardGeocode",
        "summary": "Forward geocode an address or place name to coordinates.",
        "description": "Search free-form text and return matching locations with coordinates, labels, and confidence scores. Supports country, bounding box, and circle filters plus a focus point to bias results.",
        "parameters": [
          { "name": "text", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query (e.g. an address, place name, or POI)." },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "API authentication token." },
          { "name": "size", "in": "query", "schema": { "type": "integer", "default": 10 }, "description": "Maximum number of results." },
          { "name": "boundary.country", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated ISO 3166 country codes (alpha-2 or alpha-3)." },
          { "name": "boundary.rect.min_lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.rect.min_lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.rect.max_lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.rect.max_lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.radius", "in": "query", "schema": { "type": "number", "format": "float", "default": 50 }, "description": "Radius in kilometers." },
          { "name": "boundary.gid", "in": "query", "schema": { "type": "string" }, "description": "Pelias gid for administrative-area filtering." },
          { "name": "focus.point.lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "focus.point.lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated data sources: osm, oa, gn, wof." },
          { "name": "layers", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated result layer types (e.g. address, venue, locality)." }
        ],
        "responses": {
          "200": { "description": "FeatureCollection of matching locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureCollection" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/reverse-geocode/": {
      "get": {
        "tags": ["Geocoding"],
        "operationId": "reverseGeocode",
        "summary": "Reverse geocode coordinates to address/place.",
        "parameters": [
          { "name": "point.lat", "in": "query", "required": true, "schema": { "type": "number", "format": "float" } },
          { "name": "point.lon", "in": "query", "required": true, "schema": { "type": "number", "format": "float" } },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "size", "in": "query", "schema": { "type": "integer" } },
          { "name": "boundary.country", "in": "query", "schema": { "type": "string" } },
          { "name": "boundary.circle.lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.radius", "in": "query", "schema": { "type": "number", "format": "float" }, "description": "Radius in kilometers." },
          { "name": "boundary.gid", "in": "query", "schema": { "type": "string" } },
          { "name": "sources", "in": "query", "schema": { "type": "string" } },
          { "name": "layers", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Pelias-style GeoJSON FeatureCollection with `geocoding` metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeliasFeatureCollection" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/autocomplete/": {
      "get": {
        "tags": ["Geocoding"],
        "operationId": "autocomplete",
        "summary": "Real-time address and POI autocomplete.",
        "description": "Low-latency type-ahead suggestions. Use a focus point for nearby-bias and bounding shapes to constrain results.",
        "parameters": [
          { "name": "text", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "focus.point.lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "focus.point.lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.rect.min_lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.rect.min_lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.rect.max_lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.rect.max_lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.lat", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.lon", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.circle.radius", "in": "query", "schema": { "type": "number", "format": "float" } },
          { "name": "boundary.country", "in": "query", "schema": { "type": "string" } },
          { "name": "boundary.gid", "in": "query", "schema": { "type": "string" } },
          { "name": "sources", "in": "query", "schema": { "type": "string" } },
          { "name": "layers", "in": "query", "schema": { "type": "string" } },
          { "name": "size", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "FeatureCollection of suggested locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureCollection" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/directions/": {
      "post": {
        "tags": ["Routing"],
        "operationId": "directions",
        "summary": "Turn-by-turn directions between two or more locations.",
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectionsRequest" } } }
        },
        "responses": {
          "200": { "description": "Trip with legs, maneuvers, summary, and encoded polyline shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectionsResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/isochrone/": {
      "post": {
        "tags": ["Routing"],
        "operationId": "isochrone",
        "summary": "Reachability contours (time or distance) from one or more origins.",
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsochroneRequest" } } }
        },
        "responses": {
          "200": { "description": "GeoJSON FeatureCollection of polygons or linestrings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureCollection" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/matrix/": {
      "post": {
        "tags": ["Routing"],
        "operationId": "matrix",
        "summary": "Bulk travel-time and distance matrix between sources and targets.",
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixRequest" } } }
        },
        "responses": {
          "200": { "description": "Distance/time pairs in either verbose or compact form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/optimization/": {
      "post": {
        "tags": ["Routing"],
        "operationId": "optimizeRoute",
        "summary": "Optimize the order of intermediate stops (TSP-style).",
        "description": "First and last locations stay fixed; intermediate locations are reordered to minimize travel time/distance.",
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizationRequest" } } }
        },
        "responses": {
          "200": { "description": "Optimized trip with reordered locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizationResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/map-matching/": {
      "get": {
        "tags": ["Routing"],
        "operationId": "mapMatching",
        "summary": "Snap a noisy GPS trace to the road network.",
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapMatchRequest" } } }
        },
        "responses": {
          "200": { "description": "Matched edges, admins, and encoded shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapMatchResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/elevation/": {
      "post": {
        "tags": ["Elevation"],
        "operationId": "elevation",
        "summary": "Terrain elevation along a shape of coordinates.",
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevationRequest" } } }
        },
        "responses": {
          "200": { "description": "Elevation values in meters and optional distance-elevation pairs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevationResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/styles/": {
      "get": {
        "tags": ["Tiles"],
        "operationId": "getMapStyle",
        "summary": "Fetch a vector map style JSON for use with MapLibre GL / Mapbox GL.",
        "parameters": [
          { "name": "fileName", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Style identifier in the form `YOUR_ID/style.json`." },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "MapLibre / Mapbox GL style document.", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "tokenAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "API token issued at https://portal.mapmetrics.org/keys."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid token.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Coordinate": {
        "type": "object",
        "required": ["lat", "lon"],
        "properties": {
          "lat": { "type": "number", "format": "float", "description": "Latitude in decimal degrees." },
          "lon": { "type": "number", "format": "float", "description": "Longitude in decimal degrees." }
        }
      },
      "Feature": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "const": "Feature" },
          "geometry": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "coordinates": { "type": "array", "items": { "type": "number" } }
            }
          },
          "properties": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "gid": { "type": "string" },
              "layer": { "type": "string" },
              "source": { "type": "string" },
              "name": { "type": "string" },
              "country": { "type": "string" },
              "region": { "type": "string" },
              "locality": { "type": "string" },
              "confidence": { "type": "number" },
              "distance": { "type": "number" },
              "label": { "type": "string" }
            }
          }
        }
      },
      "FeatureCollection": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "const": "FeatureCollection" },
          "features": { "type": "array", "items": { "$ref": "#/components/schemas/Feature" } },
          "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }
        }
      },
      "PeliasFeatureCollection": {
        "allOf": [
          { "$ref": "#/components/schemas/FeatureCollection" },
          {
            "type": "object",
            "properties": {
              "geocoding": {
                "type": "object",
                "properties": {
                  "version": { "type": "string" },
                  "attribution": { "type": "string" },
                  "query": { "type": "object" },
                  "engine": { "type": "object", "properties": { "name": { "type": "string" }, "author": { "type": "string" }, "version": { "type": "string" } } },
                  "timestamp": { "type": "integer" }
                }
              }
            }
          }
        ]
      },
      "Costing": {
        "type": "string",
        "enum": ["auto", "bicycle", "bus", "truck", "taxi", "motor_scooter", "pedestrian", "bikeshare"]
      },
      "DirectionsRequest": {
        "type": "object",
        "required": ["locations", "costing"],
        "properties": {
          "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" }, "minItems": 2 },
          "costing": { "$ref": "#/components/schemas/Costing" },
          "id": { "type": "string" },
          "units": { "type": "string", "enum": ["miles", "mi", "kilometers", "km"], "default": "km" },
          "language": { "type": "string", "default": "en-US", "description": "IETF BCP 47 language tag." },
          "directions_type": { "type": "string", "enum": ["none", "maneuvers", "instructions"], "default": "instructions" },
          "format": { "type": "string", "enum": ["json", "gpx", "osrm", "pbf"], "default": "json" },
          "shape_format": { "type": "string", "enum": ["polyline6", "polyline5", "geojson", "no_shape"] },
          "banner_instructions": { "type": "boolean" },
          "voice_instructions": { "type": "boolean" },
          "alternates": { "type": "integer", "description": "Alternate route count (not supported for multipoint routes)." },
          "costing_options": { "type": "object", "additionalProperties": true, "description": "Vehicle preferences such as use_tolls, use_highways." }
        }
      },
      "DirectionsResponse": {
        "type": "object",
        "properties": {
          "trip": {
            "type": "object",
            "properties": {
              "locations": { "type": "array", "items": { "type": "object" } },
              "legs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "maneuvers": { "type": "array", "items": { "type": "object" } },
                    "summary": { "type": "object", "properties": { "time": { "type": "number" }, "length": { "type": "number" }, "has_toll": { "type": "boolean" } } },
                    "shape": { "type": "string", "description": "Encoded polyline." }
                  }
                }
              },
              "summary": { "type": "object", "properties": { "time": { "type": "number" }, "length": { "type": "number" }, "has_toll": { "type": "boolean" } } },
              "status": { "type": "integer" },
              "status_message": { "type": "string" },
              "units": { "type": "string" },
              "language": { "type": "string" }
            }
          }
        }
      },
      "IsochroneRequest": {
        "type": "object",
        "required": ["locations", "costing", "contours"],
        "properties": {
          "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" }, "minItems": 1 },
          "costing": { "$ref": "#/components/schemas/Costing" },
          "contours": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "properties": {
                "time": { "type": "number", "description": "Travel time in minutes." },
                "distance": { "type": "number", "description": "Distance in kilometers." },
                "color": { "type": "string", "description": "Hex color (no #), e.g. ff0000." }
              }
            }
          },
          "date_time": {
            "type": "object",
            "properties": {
              "type": { "type": "integer", "enum": [0, 1, 2], "description": "0=current departure, 1=specified departure, 2=specified arrival." },
              "value": { "type": "string", "description": "ISO 8601 local time (YYYY-MM-DDThh:mm)." }
            }
          },
          "polygons": { "type": "boolean", "default": false },
          "denoise": { "type": "number", "minimum": 0, "maximum": 1, "default": 1 },
          "generalize": { "type": "number", "description": "Douglas-Peucker tolerance in meters." },
          "show_locations": { "type": "boolean", "default": false }
        }
      },
      "MatrixRequest": {
        "type": "object",
        "required": ["sources", "costing"],
        "properties": {
          "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } },
          "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" }, "description": "Defaults to sources if omitted." },
          "costing": { "$ref": "#/components/schemas/Costing" },
          "verbose": { "type": "boolean", "default": true },
          "shape_format": { "type": "string", "enum": ["polyline6", "polyline5", "geojson", "no_shape"] }
        }
      },
      "MatrixResponse": {
        "type": "object",
        "properties": {
          "sources_to_targets": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "distance": { "type": "number" },
                      "time": { "type": "number" },
                      "to_index": { "type": "integer" },
                      "from_index": { "type": "integer" }
                    }
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "durations": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } },
                  "distances": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }
                }
              }
            ]
          },
          "algorithm": { "type": "string", "enum": ["timedistancematrix", "costmatrix", "timedistancebssmatrix"] },
          "units": { "type": "string", "enum": ["kilometers", "miles"] },
          "warnings": { "type": "array", "items": { "type": "object" } }
        }
      },
      "OptimizationRequest": {
        "type": "object",
        "required": ["locations", "costing"],
        "properties": {
          "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" }, "minItems": 2 },
          "costing": { "type": "string", "enum": ["auto", "pedestrian", "bicycle"] },
          "units": { "type": "string", "enum": ["miles", "kilometers"], "default": "miles" }
        }
      },
      "OptimizationResponse": {
        "type": "object",
        "properties": {
          "optimized_route": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": { "trip": { "$ref": "#/components/schemas/DirectionsResponse/properties/trip" } }
            }
          },
          "units": { "type": "string" }
        }
      },
      "MapMatchRequest": {
        "type": "object",
        "required": ["shape", "costing"],
        "properties": {
          "shape": {
            "type": "array",
            "minItems": 2,
            "items": {
              "type": "object",
              "required": ["lat", "lon", "type"],
              "properties": {
                "lat": { "type": "number" },
                "lon": { "type": "number" },
                "type": { "type": "string", "enum": ["break", "via"] }
              }
            }
          },
          "costing": { "type": "string", "enum": ["auto", "pedestrian", "bicycle", "bus", "motor_scooter"] },
          "shape_match": { "type": "string", "enum": ["map_snap", "walk_or_snap", "edge_walk"], "default": "map_snap" },
          "filters": {
            "type": "object",
            "properties": {
              "attributes": { "type": "array", "items": { "type": "string" } },
              "action": { "type": "string", "enum": ["include", "exclude"] }
            }
          }
        }
      },
      "MapMatchResponse": {
        "type": "object",
        "properties": {
          "edges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "names": { "type": "array", "items": { "type": "string" } },
                "length": { "type": "number" },
                "speed": { "type": "number" },
                "road_class": { "type": "string" },
                "begin_heading": { "type": "number" },
                "end_heading": { "type": "number" }
              }
            }
          },
          "osm_changeset": { "type": "string" },
          "admins": { "type": "array", "items": { "type": "object" } },
          "shape": { "type": "string", "description": "Encoded polyline." },
          "matched_points": { "type": "array", "items": { "type": "object" } },
          "units": { "type": "string" },
          "warnings": { "type": "array", "items": { "type": "object" } }
        }
      },
      "ElevationRequest": {
        "type": "object",
        "required": ["shape"],
        "properties": {
          "shape": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } },
          "range": { "type": "boolean", "description": "If true, returns distance-elevation pairs." },
          "range_height": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }
        }
      },
      "ElevationResponse": {
        "type": "object",
        "properties": {
          "shape": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } },
          "range_height": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } },
          "height": { "type": "array", "items": { "type": "number" }, "description": "Elevation in meters." }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  }
}