{
  "openapi": "3.0.3",
  "info": {
    "title": "WortOrt API",
    "version": "1.0.0",
    "description": "Encode, decode and validate open WortOrt word addresses for coordinates."
  },
  "servers": [
    {
      "url": "https://wortort.karte.bayern",
      "description": "Public WortOrt API"
    }
  ],
  "paths": {
    "/v1/encode": {
      "post": {
        "summary": "Encode coordinates as a WortOrt code",
        "operationId": "encodeWortort",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EncodeRequest" },
              "example": { "namespace": "eu1", "lat": 48.1372, "lon": 11.5756 }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Encoded WortOrt code",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WortortResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/decode": {
      "post": {
        "summary": "Decode a WortOrt code to coordinates",
        "operationId": "decodeWortort",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CodeRequest" },
              "example": { "namespace": "eu1", "code": "eu1:wort.wort.wort.wort" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decoded location or suggestions",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WortortResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/check": {
      "post": {
        "summary": "Validate a WortOrt code without failing on invalid input",
        "operationId": "checkWortort",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CodeRequest" },
              "example": { "namespace": "eu1", "code": "wort.wort.wort.wort" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result and optional suggestions",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WortortResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/formats/encode": {
      "post": {
        "summary": "Encode coordinates into additional open coordinate formats",
        "operationId": "encodeCoordinateFormats",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CoordinateRequest" },
              "example": { "lat": 48.1372, "lon": 11.5756 }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Coordinate formats",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FormatsResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/v1/formats/decode": {
      "post": {
        "summary": "Decode an additional coordinate format to WGS84 coordinates",
        "operationId": "decodeCoordinateFormat",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/FormatDecodeRequest" },
              "example": { "format": "geohash", "value": "u281z7hm99" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decoded WGS84 location and equivalent formats",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FormatsResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EncodeRequest": {
        "type": "object",
        "required": ["lat", "lon"],
        "properties": {
          "namespace": { "type": "string", "default": "eu1", "example": "eu1" },
          "lat": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 },
          "lon": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 }
        }
      },
      "CodeRequest": {
        "type": "object",
        "required": ["code"],
        "properties": {
          "namespace": { "type": "string", "default": "eu1", "example": "eu1" },
          "code": { "type": "string", "example": "eu1:wort.wort.wort.wort" }
        }
      },
      "CoordinateRequest": {
        "type": "object",
        "required": ["lat", "lon"],
        "properties": {
          "lat": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 },
          "lon": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 }
        }
      },
      "FormatDecodeRequest": {
        "type": "object",
        "required": ["format", "value"],
        "properties": {
          "format": { "type": "string", "enum": ["geohash", "plus_code", "utm", "mgrs", "mapcode"] },
          "value": { "type": "string" }
        }
      },
      "Location": {
        "type": "object",
        "properties": {
          "lat": { "type": "number", "format": "double" },
          "lon": { "type": "number", "format": "double" }
        }
      },
      "Suggestion": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "score": { "type": "number" },
          "reason": { "type": "string" },
          "location": { "$ref": "#/components/schemas/Location" }
        }
      },
      "WortortResponse": {
        "type": "object",
        "properties": {
          "system": { "type": "string", "example": "wortort" },
          "namespace": { "type": "string", "example": "eu1" },
          "precision_m": { "type": "number", "example": 5 },
          "coverage": { "type": "string" },
          "open": { "type": "boolean" },
          "valid": { "type": "boolean" },
          "code": { "type": "string" },
          "normalized_code": { "type": "string" },
          "lat": { "type": "number", "format": "double" },
          "lon": { "type": "number", "format": "double" },
          "reason": { "type": "string" },
          "location": { "$ref": "#/components/schemas/Location" },
          "suggestions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Suggestion" }
          },
          "formats": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "FormatsResponse": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "format": { "type": "string" },
          "value": { "type": "string" },
          "lat": { "type": "number", "format": "double" },
          "lon": { "type": "number", "format": "double" },
          "formats": { "type": "object", "additionalProperties": true }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unavailable": {
        "description": "WortOrt codec unavailable",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}