📍 API de Ubicaciones Geográficas - DocuCenter

📋 Descripción

API para consultar información geográfica de Panamá, incluyendo provincias, distritos y corregimientos. No requiere autenticación.

🌐 Base URL

/api/v1/locations

📋 Endpoints

🌍 1. Obtener Todas las Ubicaciones

GET /api/v1/locations

Obtiene todas las ubicaciones disponibles organizadas por provincia con formato específico.

📤 Headers

Accept: application/json

📥 Respuesta Exitosa (200)

{
  "8": [
    [
      "PANAMA - SAN FELIPE - 8-8-1",
      "PANAMA - EL CHORRILLO - 8-8-2",
      "PANAMA - SANTA ANA - 8-8-3"
    ],
    [
      "SAN MIGUELITO - AMELIA DENIS DE ICAZA - 8-8-4",
      "SAN MIGUELITO - BELISARIO FRIAS - 8-8-5"
    ]
  ],
  "1": [
    [
      "BOCAS DEL TORO - BOCAS DEL TORO - 1-1-1",
      "BOCAS DEL TORO - BASTIMENTOS - 1-1-2"
    ]
  ]
}

🏛️ 2. Obtener Solo Provincias

GET /api/v1/locations/provincies

Obtiene la lista de todas las provincias de Panamá.

📤 Headers

Accept: application/json

📥 Respuesta Exitosa (200)

[
  {
    "id": 13,
    "nombre": "PANAMA OESTE",
    "codigo": "13"
  },
  {
    "id": 12,
    "nombre": "COMARCA NGÄBERE-BUGLÉ",
    "codigo": "12"
  },
  {
    "id": 11,
    "nombre": "COMARCA GUNA YALA",
    "codigo": "11"
  },
  {
    "id": 10,
    "nombre": "COMARCA EMBERÁ-WOUNAAN",
    "codigo": "10"
  },
  {
    "id": 9,
    "nombre": "VERAGUAS",
    "codigo": "9"
  },
  {
    "id": 8,
    "nombre": "PANAMA",
    "codigo": "8"
  },
  {
    "id": 7,
    "nombre": "LOS SANTOS",
    "codigo": "7"
  },
  {
    "id": 6,
    "nombre": "HERRERA",
    "codigo": "6"
  },
  {
    "id": 5,
    "nombre": "DARIÉN",
    "codigo": "5"
  },
  {
    "id": 4,
    "nombre": "CHIRIQUÍ",
    "codigo": "4"
  },
  {
    "id": 3,
    "nombre": "COLÓN",
    "codigo": "3"
  },
  {
    "id": 2,
    "nombre": "COCLÉ",
    "codigo": "2"
  },
  {
    "id": 1,
    "nombre": "BOCAS DEL TORO",
    "codigo": "1"
  }
]

🏛️ 3. Obtener Detalles de Provincia (Básicos)

GET /api/v1/locations/provincies/{codec}

Obtiene los detalles básicos de una provincia específica.

📝 Parámetros de Ruta

• codec (integer, requerido): Código de la provincia (1-13)

📤 Headers

Accept: application/json

📥 Respuesta Exitosa (200)

{
  "nombre": "PANAMA",
  "codigo": "8"
}

🏛️ 4. Obtener Detalles de Provincia (Completos)

GET /api/v1/locations/provincies/{codec}?full_details=1

Obtiene los detalles completos de una provincia incluyendo distritos y corregimientos.

📝 Parámetros de Ruta

• codec (integer, requerido): Código de la provincia (1-13)

🔍 Parámetros de Query

• full_details (string, opcional): Valores aceptados: 0, 1, true, false

📤 Headers

Accept: application/json

📥 Respuesta Exitosa (200)

{
  "nombre": "PANAMA",
  "codigo": "8",
  "districts": [
    {
      "id": 1,
      "nombre": "PANAMA",
      "codigo": "8",
      "corregimientos": [
        {
          "id": 1,
          "nombre": "SAN FELIPE",
          "codigo": "1",
          "codigo_ubicacion": "8-8-1"
        },
        {
          "id": 2,
          "nombre": "EL CHORRILLO",
          "codigo": "2", 
          "codigo_ubicacion": "8-8-2"
        }
      ]
    },
    {
      "id": 2,
      "nombre": "SAN MIGUELITO",
      "codigo": "9",
      "corregimientos": [
        {
          "id": 3,
          "nombre": "AMELIA DENIS DE ICAZA",
          "codigo": "1",
          "codigo_ubicacion": "8-9-1"
        }
      ]
    }
  ]
}

❌ Respuesta de Error (404)

{
  "message": "No query results for model [App\\Models\\Province] 99"
}

📍 5. Obtener Detalles de Ubicación Específica

GET /api/v1/locations/{locationCode}

Obtiene los detalles completos de una ubicación específica usando su código de ubicación.

📝 Parámetros de Ruta

• locationCode (string, requerido): Código completo de la ubicación (ej: "8-8-1")

📤 Headers

Accept: application/json

📥 Respuesta Exitosa (200)

{
  "provincia": {
    "id": 8,
    "nombre": "PANAMA",
    "codigo": "8"
  },
  "distrito": {
    "id": 1,
    "nombre": "PANAMA", 
    "codigo": "8"
  },
  "corregimiento": {
    "id": 1,
    "nombre": "SAN FELIPE",
    "codigo": "1",
    "codigo_ubicacion": "8-8-1"
  }
}

❌ Respuesta de Error (404)

{
  "message": "No query results for model [App\\Models\\Corregimiento] 8-8-99"
}

❌ Respuesta de Error (400) - Formato Inválido

{
  "message": "Invalid location code format."
}

📊 Estructura de Datos

🏛️ Provincia

🏘️ Distrito

🏠 Corregimiento

💡 Casos de Uso

1. Listar Todas las Ubicaciones (Para Dropdown)

curl -X GET "http://localhost:8000/api/v1/locations" \
     -H "Accept: application/json"

2. Obtener Solo Provincias

curl -X GET "http://localhost:8000/api/v1/locations/provincies" \
     -H "Accept: application/json"

3. Consultar Provincia (Básico)

curl -X GET "http://localhost:8000/api/v1/locations/provincies/8" \
     -H "Accept: application/json"

4. Consultar Provincia (Completo)

curl -X GET "http://localhost:8000/api/v1/locations/provincies/8?full_details=1" \
     -H "Accept: application/json"

5. Obtener Ubicación por Código

curl -X GET "http://localhost:8000/api/v1/locations/8-8-1" \
     -H "Accept: application/json"

📊 Códigos de Estado HTTP

⚠️ Notas Adicionales

• Sin autenticación: Todos los endpoints son públicos
• Nombres en mayúsculas: Todos los nombres vienen en mayúsculas desde la base de datos
• Orden descendente: Las provincias se devuelven ordenadas por ID descendente
• Formato de código: Los códigos de ubicación siguen el formato provincia-distrito-corregimiento
• Validación de formato: El código de ubicación debe tener exactamente 3 partes separadas por guiones
• Datos de prueba: El test confirma que "8-8-1" corresponde a "PANAMA - PANAMA - SAN FELIPE"

📞 Soporte

Para soporte con ubicaciones geográficas:

• Email: desarrollo@apconpanama.me
• GitHub: Reportar Issues
• Documentación: Índice de APIs