{
  "openapi": "3.1.0",
  "info": {
    "title": "EuroPostcode API",
    "version": "2026-09-07",
    "description": "European postcode normalization, lookup, autocomplete and spatial reference API. Coordinates are reference points, not proof of deliverability."
  },
  "servers": [{ "url": "https://europostcode.com/api/v1" }],
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } },
    "schemas": {
      "Postcode": {
        "type": "object",
        "properties": {
          "postcode": { "type": "string" },
          "normalizedPostcode": { "type": "string" },
          "countryCode": { "type": "string" },
          "zone": { "type": "string" },
          "locality": { "type": "string" },
          "longitude": { "type": "number" },
          "latitude": { "type": "number" },
          "precision": { "type": "string" },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "source": { "type": "string" },
          "dataVersion": { "type": ["string", "null"] },
          "distanceKm": { "type": "number" },
          "regions": { "type": "object" }
        }
      }
    }
  },
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/status": { "get": { "security": [], "summary": "Service status", "responses": { "200": { "description": "Healthy" } } } },
    "/coverage": { "get": { "security": [], "summary": "Coverage, versions and licences", "responses": { "200": { "description": "Coverage metadata" } } } },
    "/postcodes/{country}/{postcode}": { "get": { "summary": "Exact postcode lookup", "parameters": [{ "in": "path", "name": "country", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "postcode", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Lookup result" } } } },
    "/postcodes/normalize": { "get": { "summary": "Normalize and validate a postcode", "parameters": [{ "in": "query", "name": "country", "schema": { "type": "string" } }, { "in": "query", "name": "postcode", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Normalized result" } } } },
    "/postcodes/autocomplete": { "get": { "summary": "Autocomplete a postcode prefix", "parameters": [{ "in": "query", "name": "q", "required": true, "schema": { "type": "string", "minLength": 2 } }, { "in": "query", "name": "country", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "maximum": 20 } }], "responses": { "200": { "description": "Suggestions" } } } },
    "/postcodes/nearby": { "get": { "summary": "Find postcodes within a radius", "parameters": [{ "in": "query", "name": "lat", "required": true, "schema": { "type": "number" } }, { "in": "query", "name": "lng", "required": true, "schema": { "type": "number" } }, { "in": "query", "name": "radiusKm", "schema": { "type": "number", "maximum": 250 } }, { "in": "query", "name": "country", "schema": { "type": "string" } }], "responses": { "200": { "description": "Distance-sorted postcodes" } } } },
    "/postcodes/reverse": { "get": { "summary": "Find the closest postcode reference point", "parameters": [{ "in": "query", "name": "lat", "required": true, "schema": { "type": "number" } }, { "in": "query", "name": "lng", "required": true, "schema": { "type": "number" } }, { "in": "query", "name": "country", "schema": { "type": "string" } }], "responses": { "200": { "description": "Closest known postcode" } } } },
    "/postcodes/batch": { "post": { "summary": "Validate postcode batches", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Batch results" } } } }
  }
}