{
  "openapi": "3.1.0",
  "info": {
    "title": "Retailer Search API",
    "version": "1.0.0",
    "description": "First-party retailer lookup for brand sites. Prefer this endpoint for machine-readable retrieval. Provide either q or lat+lng."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/api/retailers/search": {
      "get": {
        "operationId": "searchRetailers",
        "summary": "Search retailers by location query or coordinates",
        "description": "Returns nearby retailers for an allowlisted brand tag. Use q for geocoded place search, or lat+lng for direct coordinate search.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Location query such as town, city, or postcode.",
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "examples": {
              "city": {
                "value": "oxford"
              },
              "postcode": {
                "value": "SW1A 1AA"
              }
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "description": "Latitude in decimal degrees. Must be provided with lng when q is omitted.",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "description": "Longitude in decimal degrees. Must be provided with lat when q is omitted.",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Brand tag. Must be one of the project allowlisted tag values.",
            "schema": {
              "type": "string",
              "examples": [
                "nutrak",
                "mpart",
                "truflo"
              ]
            }
          },
          {
            "name": "distance",
            "in": "query",
            "required": false,
            "description": "Search distance in miles. Defaults to 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max results to return. Defaults to 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Retailer search response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetailerSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (missing q/lat/lng or invalid tag/range)"
          },
          "404": {
            "description": "No geocode result for q"
          },
          "502": {
            "description": "Upstream dealer source error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RetailerSearchResponse": {
        "type": "object",
        "required": [
          "ok",
          "source",
          "query",
          "count",
          "results"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "source": {
            "type": "string",
            "format": "uri"
          },
          "query": {
            "type": "object",
            "required": [
              "tag",
              "distance",
              "limit",
              "lat",
              "lng"
            ],
            "properties": {
              "q": {
                "type": "string"
              },
              "tag": {
                "type": "string"
              },
              "distance": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              },
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dealer"
            }
          }
        }
      },
      "Dealer": {
        "type": "object",
        "required": [
          "name",
          "latitude",
          "longitude"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "address_line1": {
            "type": "string"
          },
          "address_line2": {
            "type": "string"
          },
          "address_line3": {
            "type": "string"
          },
          "address_line4": {
            "type": "string"
          },
          "address_line5": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "telephone": {
            "type": "string"
          },
          "latitude": {
            "type": [
              "string",
              "number"
            ]
          },
          "longitude": {
            "type": [
              "string",
              "number"
            ]
          },
          "distance_miles": {
            "type": "number",
            "description": "Computed straight-line distance from query center to retailer, in miles."
          },
          "icon": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  }
}