All Nation API v1.0

Introducción

All Nation API es una herramienta backend que proporciona acceso a información organizada de países, regiones y localidades. Esta API te permite obtener listas de países, explorar regiones según el tipo de organización administrativa de cada país, y descubrir todas las localidades dentro de esas regiones.

Uso General

La API está diseñada para gestionar datos geográficos de manera eficiente. Requiere especificar parámetros de búsqueda y límite en tus consultas para obtener resultados precisos.

Todos los endpoints requieren los siguientes parámetros:

  • search: Término de búsqueda para filtrar resultados.
  • limit: Número máximo de resultados a devolver (máximo 100).

Endpoints

1. Obtener países

Busca entre todas los paises disponibles del mundo

GET /v1/countries
Parámetro Descripción
search Término de búsqueda para filtrar países
limit Número máximo de resultados a devolver

Ejemplo de respuesta:

[
  { "id": 1, "name": "Argentina", "iso_code": "AR" },
  { "id": 2, "name": "Armenia", "iso_code": "AM" }
]

2. Obtener detalles de un país

Detalles de un pais

GET /v1/countries/{id}
Parámetro Descripción
id ID del país

Ejemplo de respuesta:

{
  "id": 1,
  "name": "Argentina",
  "iso_code": "AR"
}

3. Obtener regiones de un país

Busca entre todas regiones disponibles de un pais

GET /v1/countries/{countryId}/regions
Parámetro Descripción
countryId ID del país
search Término de búsqueda para filtrar regiones
limit Número máximo de resultados a devolver

Ejemplo de respuesta:

[
  {
    "id": 2,
    "country_id": 21,
    "administrative_type_id": 3,
    "region_name": "Cochabamba",
    "country_name": "Bolivia",
    "administrative_type_name": "Departamento"
  }
]

4. Obtener localidades de una región

Busca entre todas las localidades disponibles de una region

GET /v1/localities/region/{regionId}
Parámetro Descripción
regionId ID de la región
search Término de búsqueda para filtrar localidades
limit Número máximo de resultados a devolver

Ejemplo de respuesta:

[
  {
    "id": 91,
    "name": "Quillacollo",
    "region_name": "Cochabamba",
    "country_name": "Bolivia"
  }
]

5. Obtener localidades por pais

Busca entre todas las localidades disponibles de un pais

GET /v1/localities/country/{id country}
Parámetro Descripción
countryId ID del paisn
search Término de búsqueda para filtrar localidades
limit Número máximo de resultados a devolver

Ejemplo de respuesta:

[
  {
    "id": 95,
    "name": "Vinto",
    "region_name": "Cochabamba",
    "country_name": "Bolivia"
  }
]

6. Obtener tipos de divisiones administrativas

GET /v1/administrative-types
Parámetro Descripción
search Término de búsqueda para filtrar tipos administrativos
limit Número máximo de resultados a devolver

Ejemplo de respuesta:

[
    {"id":2,"name":"Provincia"}
]

Errores Comunes

  • 400 Bad Request: Los parámetros de la solicitud son inválidos o están incompletos.
  • 404 Not Found: El recurso solicitado no existe.
  • 429 Too Many Requests: Se ha excedido el límite de solicitudes.
  • 500 Internal Server Error: Error inesperado del servidor.

Consejos para evitar errores comunes:

  • No especificar search o limit: Asegúrate de incluir siempre ambos parámetros en las solicitudes que los requieran.
  • No encontrar resultados con search: Revisa los términos de búsqueda y ajusta los valores si es necesario. Considera usar términos más generales si no obtienes resultados.
  • Exceder el límite de solicitudes: Implementa un sistema de caché en tu aplicación para reducir el número de llamadas a la API.

Ejemplos de Uso

Ejemplo 1: Obtener países que contienen "united" en su nombre

GET /v1/countries?search=united&limit=5

Respuesta:
[
  { "id": 225, "name": "United States", "iso_code": "US" },
  { "id": 226, "name": "United Kingdom", "iso_code": "GB" },
  { "id": 3, "name": "United Arab Emirates", "iso_code": "AE" }
]

Ejemplo 2: Obtener regiones de España que contienen "valencia" en su nombre

GET /v1/countries/195/regions?search=valencia&limit=2

Respuesta:
[
  { "id": 1987, "name": "Comunidad Valenciana", "country_id": 195 },
  { "id": 1988, "name": "Valencia", "country_id": 195 }
]

Ejemplo 3: Obtener localidades en la región de Cataluña que contienen "barcelona" en su nombre

GET /v1/localities/region/1978?search=barcelona&limit=3

Respuesta:
[
  { "id": 19780, "name": "Barcelona", "region_id": 1978 },
  { "id": 19781, "name": "L'Hospitalet de Llobregat", "region_id": 1978 },
  { "id": 19782, "name": "Badalona", "region_id": 1978 }
]

Mejores Prácticas

  • Caché: Implementa un sistema de caché en tu aplicación para almacenar resultados frecuentes y reducir las llamadas a la API.
  • Paginación: Utiliza el parámetro 'limit' de manera efectiva para implementar la paginación en tu aplicación.
  • Manejo de errores: Implementa un manejo robusto de errores en tu aplicación para gestionar adecuadamente las respuestas de error de la API.
  • Retroalimentación al usuario: Proporciona mensajes claros al usuario final cuando los resultados de búsqueda estén vacíos o ocurran errores.
  • Monitoreo: Mantén un registro de tus llamadas a la API para detectar patrones de uso y optimizar tu implementación.

Actualizaciones y Cambios

Nos esforzamos por mantener la estabilidad de la API, pero ocasionalmente pueden ocurrir cambios. Te recomendamos:

  • Revisar regularmente esta documentación para estar al tanto de nuevas características o cambios.
  • Estar atento a las notas de la versión que publicamos para conocer los detalles de cada actualización.
  • Seguir nuestro perfil de GitHub obed-tc para acceder a ejemplos de código y contribuir al desarrollo de la API.

Tu feedback es importante para nosotros, así que no dudes en contactarnos si tienes sugerencias o comentarios.

Créditos

Desarrollado por obed-tc