{
  "openapi": "3.0.3",
  "info": {
    "title": "BLACAMP Public API",
    "description": "Public REST API for BLACAMP — Europe's outdoor adventure directory indexing over 46,000 verified campsites, RV camper areas, mountain routes, and outdoor businesses across 48 European countries.",
    "version": "1.0.0",
    "contact": {
      "name": "BLACAMP Developer Relations",
      "email": "info@blacamp.com",
      "url": "https://blacamp.com/docs"
    },
    "license": {
      "name": "Creative Commons Attribution 4.0 International",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://blacamp.com",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/buscar": {
      "get": {
        "operationId": "searchDirectory",
        "summary": "Search campsites, RV areas and outdoor sports destinations",
        "description": "Full-text multi-criteria search across 46,000+ European outdoor destinations. Supports filtering by query keywords, country code, province, and amenities.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query text (e.g., 'camping costa brava', 'glamping pirineos')",
            "required": false,
            "schema": {
              "type": "string",
              "example": "camping"
            }
          },
          {
            "name": "pais",
            "in": "query",
            "description": "Two-letter ISO 3166-1 alpha-2 country code (e.g., 'es', 'fr', 'de', 'it', 'pt')",
            "required": false,
            "schema": {
              "type": "string",
              "example": "es"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of records to return (1-100)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching outdoor destinations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "description": "Total count of matching results",
                      "example": 42
                    },
                    "resultados": {
                      "type": "array",
                      "description": "Array of destination objects",
                      "items": {
                        "$ref": "#/components/schemas/DestinationSummary"
                      }
                    }
                  },
                  "required": ["total", "resultados"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters"
          }
        }
      }
    },
    "/api/explorar/sugerencias": {
      "get": {
        "operationId": "autocompleteLocations",
        "summary": "Autocomplete suggestions for locations, regions and activities",
        "description": "Returns fast typeahead suggestions matching places, provinces, regions, and outdoor sports disciplines across Europe.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Prefix query term (at least 2 characters)",
            "required": true,
            "schema": {
              "type": "string",
              "example": "cata"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching autocomplete items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sugerencias": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SuggestionItem"
                      }
                    }
                  },
                  "required": ["sugerencias"]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DestinationSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
          },
          "nombre": {
            "type": "string",
            "example": "Camping Mas Nou"
          },
          "slug": {
            "type": "string",
            "example": "camping-mas-nou"
          },
          "provincia": {
            "type": "string",
            "example": "Girona"
          },
          "pais": {
            "type": "string",
            "example": "España"
          },
          "lat": {
            "type": "number",
            "format": "float",
            "example": 42.1583
          },
          "lng": {
            "type": "number",
            "format": "float",
            "example": 3.0841
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://blacamp.com/empresa/camping-mas-nou"
          }
        },
        "required": ["id", "nombre", "slug", "url"]
      },
      "SuggestionItem": {
        "type": "object",
        "properties": {
          "titulo": {
            "type": "string",
            "example": "Catalunya"
          },
          "tipo": {
            "type": "string",
            "enum": ["region", "provincia", "categoria", "empresa"],
            "example": "region"
          },
          "url": {
            "type": "string",
            "example": "/es/catalunya"
          }
        },
        "required": ["titulo", "tipo", "url"]
      }
    }
  }
}