{
  "openapi": "3.0.3",
  "info": {
    "title": "OSRM Routing API",
    "version": "1.0.0",
    "description": "Driving distance, travel time and the route line between places. Authenticate with your API key: `Authorization: Bearer <key>` (or `X-Api-Key`). Coordinates you send are `lat,lng`; GeoJSON geometry coordinates in answers are `[lng, lat]`."
  },
  "servers": [{ "url": "https://YOUR-DOMAIN/osrm-api/v1", "description": "Replace with the address of your installation" }],
  "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
  "paths": {
    "/route": {
      "get": {
        "summary": "Route between two places",
        "parameters": [
          { "name": "from", "in": "query", "schema": { "type": "string", "example": "31.5204,74.3587" }, "description": "Start as lat,lng (with `to`)" },
          { "name": "to", "in": "query", "schema": { "type": "string", "example": "33.6844,73.0479" }, "description": "End as lat,lng (with `from`)" },
          { "name": "points", "in": "query", "schema": { "type": "string", "example": "31.52,74.35;32.1,73.9;33.68,73.04" }, "description": "Alternative to from/to: 2 to 10 lat,lng pairs separated by semicolons" },
          { "name": "geometry", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Also return the line to draw (GeoJSON)" }
        ],
        "responses": {
          "200": { "description": "The route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" } } } },
          "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }
        }
      },
      "post": {
        "summary": "Route through several places (JSON body)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["points"],
          "properties": { "points": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "example": [[31.5204, 74.3587], [33.6844, 73.0479]] }, "geometry": { "type": "boolean" } }
        } } } },
        "responses": { "200": { "description": "The route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" } } } }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/health": {
      "get": {
        "summary": "Is the routing server up?",
        "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "osrm": { "type": "string", "enum": ["up", "down"] }, "time": { "type": "string", "format": "date-time" } } } } } } }
      }
    },
    "/usage": {
      "get": {
        "summary": "Your limits and remaining quota",
        "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "user": { "type": "string" },
          "limits": { "type": "object", "properties": { "per_minute": { "type": "integer" }, "per_day": { "type": "integer" }, "per_month": { "type": "integer" } }, "description": "0 = unlimited" },
          "used": { "type": "object", "properties": { "last_minute": { "type": "integer" }, "today": { "type": "integer" }, "this_month": { "type": "integer" } } },
          "remaining": { "type": "object", "properties": { "per_minute": { "type": "integer", "nullable": true }, "today": { "type": "integer", "nullable": true }, "this_month": { "type": "integer", "nullable": true } } }
        } } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }
    },
    "schemas": {
      "Route": {
        "type": "object",
        "properties": {
          "distance_km": { "type": "number", "example": 294.48 },
          "duration_min": { "type": "number", "example": 298.2 },
          "geometry": { "type": "object", "nullable": true, "description": "GeoJSON LineString, coordinates are [lng, lat]. Only with geometry=1." },
          "source": { "type": "string", "enum": ["osrm", "estimate"], "description": "estimate = the routing server did not answer; straight-line distance x 1.35 at 25 km/h" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "object", "properties": {
          "code": { "type": "string", "enum": ["missing_key", "invalid_key", "revoked_key", "account_suspended", "unknown_action", "bad_points", "bad_coordinate", "rate_limited", "daily_quota_exceeded", "monthly_quota_exceeded"] },
          "message": { "type": "string" }
        } } }
      }
    },
    "responses": {
      "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}
