Buscar ciudades

Busca ciudades por nombre, código SIFEN, distrito o departamento. Permite búsquedas flexibles con múltiples palabras. Retorna la información completa con distrito y departamento anidados.

Entorno

URL base: https://api.guarani.app

Endpoint

GET /ciudades/search?q={query}&page={page}&limit={limit}

Ejemplo de solicitud

curl -X GET "https://api.guarani.app/ciudades/search?q={query}&page=1&limit=10" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | jq

Nota: El parámetro de búsqueda q puede contener el nombre de la ciudad, código SIFEN, distrito o departamento. Búsqueda inteligente: Si se proporcionan varias palabras, todas deben aparecer en alguno de los campos (ciudad, distrito o departamento). Esta búsqueda puede coincidir por cualquier dato relacionado: nombre/código SIFEN de la ciudad, del distrito o del departamento.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`q`	`string`	Sí	Parámetro de búsqueda
`page`	`integer`	No	Número de página. Por defecto: `1`.
`limit`	`integer`	No	Resultados por página. Por defecto: `10`.

Encabezados de la solicitud

Encabezado	Valor	Descripción
`x-api-key`	`Bearer <access_token>`	Token de autenticación necesario para acceder al recurso.
`Accept`	`application/json`	Indica que la respuesta debe devolverse en formato JSON.

Ejemplo de respuesta

{
  "success": true,
  "codigo": 200,
  "message": "Operación realizada correctamente.",
  "data": [
    {
      "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
      "codigo_sifen": "3556",
      "nombre": "SANTA RITA",
      "distrito": {
        "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
        "codigo_sifen": "209",
        "nombre": "SANTA RITA",
        "departamento": {
          "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
          "codigo_sifen": "11",
          "nombre": "ALTO PARANA"
        }
      }
    }
  ],
  "pagination": {
    "total_registros": 1,
    "pagina": 1,
    "total_paginas": 1
  }
}

Recursos adicionales

Para buscar ciudades filtradas por distrito, consulta Buscar ciudades por distrito
Para obtener una ciudad específica por ID, consulta Obtener ciudad por ID
Para listar todas las ciudades con paginación, consulta Obtener ciudades
Para obtener ciudades de un distrito específico, consulta Obtener ciudades por distrito
Para información sobre errores, consulta Códigos de error