Documentación de la API - Endpoints y Ejemplos

Validación de Direcciones

Comprueba que una dirección existe y recupérala en forma canónica

El endpoint /v1/places/validate recibe el país, el estado, la ciudad y el código postal que ha escrito un usuario y te dice si esa combinación existe realmente —componente a componente—, devolviendo la escritura canónica y, cuando algo no cuadra, la corrección más próxima.

Es el último paso antes de guardar una dirección de envío: el autocompletado guía al usuario y esto confirma con qué se ha quedado, incluidas las direcciones escritas a mano o importadas desde otro sitio.

Endpoint

GET  https://api.countrydataapi.com/v1/places/validate
POST https://api.countrydataapi.com/v1/places/validate

Ambos aceptan los mismos campos. GET es una petición CORS simple, así que funciona desde el navegador sin preflight; POST los recibe en un cuerpo JSON.

Parámetros

Parámetro Tipo Requerido Descripción
apikey string Sí Tu clave de autenticación API
country string Sí Id interno, ISO-2, ISO-3 o nombre
state string No Nombre del estado o provincia
city string No Nombre de la ciudad
zipcode string No Código postal
lang string No Idioma de los nombres devueltos. Por defecto en

Los componentes que no envías vuelven con el veredicto not_provided: nada de lo que omitas puede invalidar la dirección.

Ejemplo de Solicitud

curl "https://api.countrydataapi.com/v1/places/validate?apikey=tu-clave-api&country=ES&state=Madrid&city=Madrid&zipcode=28001&lang=es"

POST con cuerpo JSON

const response = await fetch(
  'https://api.countrydataapi.com/v1/places/validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apikey: 'tu-clave-api',
      country: 'ES',
      state: 'Madrid',
      city: 'Madrid',
      zipcode: '28001',
      lang: 'es',
    }),
  }
);
const { result } = await response.json();

SDK de TypeScript

const { result } = await api.places.validate({
  country: 'ES',
  zipcode: '28001',
  lang: 'es',
});

result.normalized.state?.name; // "Comunidad de Madrid"

Formato de Respuesta

{
  "success": true,
  "result": {
    "valid": true,
    "has_corrections": false,
    "verdict": {
      "country": "confirmed",
      "state": "confirmed",
      "city": "confirmed",
      "zipcode": "confirmed"
    },
    "normalized": {
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "España",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Comunidad de Madrid" },
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
      "zipcode": "28001"
    },
    "corrections": [],
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345",
      "matches_format": true
    }
  },
  "tokens_used": 1,
  "remaining_tokens": 4870
}

Veredictos

Veredicto Significado
confirmed El valor existe y coincide exactamente con lo enviado
corrected El componente se ha resuelto, pero no a partir de lo enviado — mira corrections
unconfirmed El valor no ha podido verificarse
not_provided No enviaste este componente

valid es true solo cuando todos los componentes que enviaste han vuelto como confirmed. Usa has_corrections para decidir si mostrar al usuario un «¿quisiste decir...?» en lugar de un error.

Un código postal por sí solo resuelve el estado

El caso habitual en un checkout: solo has pedido código postal y ciudad.

curl "https://api.countrydataapi.com/v1/places/validate?apikey=tu-clave-api&country=ES&zipcode=28001&lang=es"

La respuesta rellena normalized.state a partir del código postal, así que puedes completar el campo de provincia por el usuario en vez de pedírselo. Funciona igual al revés: envía una ciudad y el estado vuelve resuelto.

Cuando el código postal no está en nuestro listado

La cobertura de códigos postales no es completa para todos los países. Si un código no está listado pero sí encaja con el formato oficial del país, el veredicto es corrected en lugar de unconfirmed, y postal.matches_format vale true. Trátalo como «plausible, acéptalo» salvo que tu caso de uso exija certeza.

matches_format es null cuando el país no tiene un patrón oficial registrado.

Ejemplo de corrección

{
  "valid": false,
  "has_corrections": true,
  "verdict": { "country": "confirmed", "state": "unconfirmed", "city": "confirmed", "zipcode": "not_provided" },
  "corrections": [
    { "component": "state", "input": "Cataluna", "suggestion": "Cataluña" }
  ]
}

Consumo de Tokens

Este endpoint consume 1 token por petición, sin importar cuántos componentes envíes.

Endpoints Relacionados