Documentación de la API - Endpoints y Ejemplos

Detalle del Lugar

Todo lo que necesitas en cuanto el usuario elige una sugerencia

El endpoint /v1/places/details recibe el id de una sugerencia del autocompletado y devuelve la ficha completa: la jerarquía entera, el formato de código postal del país y los datos que un formulario suele necesitar a continuación — prefijo telefónico, moneda, husos horarios.

Endpoint

GET https://api.countrydataapi.com/v1/places/details

Parámetros de Consulta

Parámetro Tipo Requerido Descripción
apikey string Sí Tu clave de autenticación API
id string Sí El id devuelto por /v1/places/autocomplete
type string Sí country, state o city — el type de la sugerencia
lang string No Idioma de los nombres devueltos. Por defecto en
sessiontoken string No El token de sesión usado durante el autocompletado. Hace que esta llamada sea gratuita

Ejemplo de Solicitud

curl "https://api.countrydataapi.com/v1/places/details?apikey=tu-clave-api&id=66c7a6c9e4bda21f4ab1a0f1&type=city&lang=es"

JavaScript

async function getDetails(suggestion, sessionToken) {
  const params = new URLSearchParams({
    apikey: 'tu-clave-api',
    id: suggestion.id,
    type: suggestion.type,
    lang: 'es',
    sessiontoken: sessionToken,
  });

  const response = await fetch(
    `https://api.countrydataapi.com/v1/places/details?${params}`
  );
  const { place } = await response.json();
  return place;
}

SDK de TypeScript

const { place } = await api.places.details({
  id: suggestion.id,
  type: suggestion.type,
  sessiontoken: session,
});

place.components.country?.phone_code; // "+34"
place.postal.regex;                   // "^\\d{5}$"

Formato de Respuesta

{
  "success": true,
  "place": {
    "id": "66c7a6c9e4bda21f4ab1a0f1",
    "type": "city",
    "name": "Madrid",
    "description": "Madrid, Comunidad de Madrid, España",
    "components": {
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Comunidad de Madrid" },
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "España",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      }
    },
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345"
    },
    "location": null,
    "country_info": {
      "currencies": [{ "code": "EUR", "name": "Euro", "symbol": "€" }],
      "languages": ["Español"],
      "timezones": ["UTC+01:00"],
      "continent": "EU",
      "region": "Europe"
    }
  },
  "tokens_used": 0,
  "remaining_tokens": 4871
}

Campos de la Respuesta

Campo Tipo Descripción
place.components object Jerarquía completa: city, state, country
place.postal.format string Plantilla: # es un dígito, @ es una letra
place.postal.regex string Patrón oficial de código postal del país
place.postal.example string Valor de ejemplo derivado de format y verificado contra regex
place.location object Coordenadas — ver la nota más abajo
place.country_info object Monedas, idiomas, husos horarios, continente y región

Sobre location

location solo viene relleno para type=country, donde lleva el centroide del país y "precision": "country".

Para estados y ciudades es null. El conjunto de datos es administrativo y no tiene coordenadas por ciudad, y devolver el centroide del país etiquetado como si fuera la ciudad sería peor que no devolver nada. Si necesitas coordenadas a nivel de ciudad o geocodificación, este endpoint no es la herramienta adecuada.

Consumo de Tokens

  • 0 tokens cuando sessiontoken corresponde a una sesión de autocompletado abierta. La sesión ya se cobró en la primera tecla, y esta llamada la cierra.
  • 1 token en cualquier otro caso.

Esto significa que un campo de dirección completo —todas las teclas que haga falta más la consulta final del detalle— cuesta un solo token.

Respuesta de Error

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No city found with id \"abc\".",
    "status": 404
  },
  "message": "No city found with id \"abc\"."
}

Endpoints Relacionados