{
  "openapi": "3.0.3",
  "info": {
    "title": "Eircode Lookup API",
    "version": "1.0.0",
    "description": "Resolve Eircodes and Irish addresses to coordinates, formatted address, and a Google Maps link. Distributed exclusively via RapidAPI — get your API key at https://rapidapi.com/forcequit/api/eircode1.",
    "contact": { "name": "Eircode Lookup API", "url": "https://eircode.dev" },
    "license": { "name": "MIT" }
  },
  "servers": [
    { "url": "https://eircode-api.p.rapidapi.com", "description": "RapidAPI (production)" }
  ],
  "security": [{ "RapidApiKey": [], "RapidApiHost": [] }],
  "tags": [{ "name": "Lookup", "description": "Eircode / address resolution" }],
  "paths": {
    "/api/eircode": {
      "get": {
        "tags": ["Lookup"],
        "summary": "Look up an Eircode or address (query string)",
        "operationId": "lookupEircodeGet",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Eircode (e.g. `D02 X285`) or Irish address. 2-200 chars.",
            "schema": { "type": "string", "minLength": 2, "maxLength": 200 },
            "example": "D02 X285"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful lookup",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": {
                  "ok": true,
                  "query": "D02 X285",
                  "formattedAddress": "Saint Kevin's, Dublin, Co. Dublin, D02 X285, Ireland",
                  "eircode": "D02 X285",
                  "location": { "lat": 53.3320669, "lng": -6.255491699999999 },
                  "placeId": "ChIJgclyraMOZ0gRRA_QJFnS6VA",
                  "embedUrl": "https://www.google.com/maps/search/?api=1&query=53.3320669,-6.255491699999999&query_place_id=ChIJgclyraMOZ0gRRA_QJFnS6VA",
                  "tookMs": 111
                }
              }
            }
          },
          "400": {
            "description": "Validation error, no match, or upstream geocoding failure",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "ok": false, "error": "No match found in Ireland for that input.", "tookMs": 87 }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Lookup"],
        "summary": "Look up an Eircode or address (JSON body)",
        "operationId": "lookupEircodePost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string", "minLength": 2, "maxLength": 200, "example": "Trinity College Dublin" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful lookup",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }
          },
          "400": {
            "description": "Validation error, no match, or upstream geocoding failure",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "RapidApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Key",
        "description": "Your RapidAPI subscription key from https://rapidapi.com/forcequit/api/eircode1."
      },
      "RapidApiHost": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Host",
        "description": "Must be `eircode-api.p.rapidapi.com`."
      }
    },
    "schemas": {
      "SuccessResponse": {
        "type": "object",
        "required": ["ok", "query", "formattedAddress", "eircode", "location", "placeId", "embedUrl", "tookMs"],
        "properties": {
          "ok": { "type": "boolean", "enum": [true] },
          "query": { "type": "string" },
          "formattedAddress": { "type": "string" },
          "eircode": { "type": "string", "nullable": true, "description": "Eircode in `A65 F4E2` format, or null if not resolvable." },
          "location": {
            "type": "object",
            "required": ["lat", "lng"],
            "properties": {
              "lat": { "type": "number", "format": "double" },
              "lng": { "type": "number", "format": "double" }
            }
          },
          "placeId": { "type": "string", "description": "Google Maps Place ID." },
          "embedUrl": { "type": "string", "format": "uri", "description": "Public Google Maps URL pointing to the location." },
          "tookMs": { "type": "integer", "description": "Server-side processing time in milliseconds." }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["ok", "error", "tookMs"],
        "properties": {
          "ok": { "type": "boolean", "enum": [false] },
          "error": { "type": "string" },
          "tookMs": { "type": "integer" }
        }
      }
    }
  }
}