Country Data API proporciona información detallada sobre +200 países diferentes

Descripción general

El endpoint /v1/zipcodes/all devuelve una lista completa de todos los códigos postales de todas las ciudades del mundo. Este endpoint es ideal para aplicaciones que necesitan poblar bases de datos con información completa de códigos postales.

Endpoint

GET https://api.countrydataapi.com/v1/zipcodes/all

Autenticación

Incluye tu clave API como parámetro de consulta:

?apikey=tu-clave-api

Tu clave API es como una contraseña, mantenla segura. Obtén tu clave desde el panel de cuenta.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`apikey`	string	Sí	Tu clave de autenticación API
`lang`	string	No	Código de idioma para la respuesta (predeterminado: `en`)
`limitToken`	number	No	Máximo de tokens a gastar en esta petición (predeterminado: `1000`)

Idiomas soportados

en - Inglés (predeterminado)
es - Español
pt - Portugués
fr - Francés
de - Alemán
it - Italiano

Uso de tokens

Cada código postal devuelto costará 1 token.

Importante: Este endpoint puede devolver una gran cantidad de datos. Usa limitToken para controlar costos e implementa paginación para conjuntos de datos grandes.

Formato de respuesta

Respuesta exitosa

[
  {
    "id": "8dd25479-067a-43b0-ac4a-8e7faf2bcaf",
    "country_name": "Algeria",
    "state_names": [
      {
        "id": "8dd25479-067a-43b0-ac4a-8e7faf2bcad",
        "name": "Oran",
        "postal_code": [
          "31004",
          "31016",
          "31019",
          "31020"
        ]
      }
    ]
  },
  {
    "id": "9ae35480-178b-54c1-bd5b-9f8gbf3cdeg",
    "country_name": "United States",
    "state_names": [
      {
        "id": "9ae35480-178b-54c1-bd5b-9f8gbf3cdeh",
        "name": "California",
        "postal_code": [
          "90001",
          "90002",
          "90003"
        ]
      }
    ]
  }
]

Campos de respuesta

Campo	Tipo	Descripción
`id`	string	Identificador único del país
`country_name`	string	Nombre del país en el idioma solicitado
`state_names`	array	Array de objetos de estado que contienen códigos postales
`state_names[].id`	string	Identificador único del estado
`state_names[].name`	string	Nombre del estado/provincia
`state_names[].postal_code`	array	Array de códigos postales para este estado

Respuesta de error

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Consulta la documentación de códigos de error para todos los códigos de error posibles.

Ejemplos de código

cURL

curl -X GET "https://api.countrydataapi.com/v1/zipcodes/all?apikey=tu-clave-api&lang=en&limitToken=100"

JavaScript (Fetch)

const API_KEY = 'tu-clave-api';
const BASE_URL = 'https://api.countrydataapi.com/v1';

async function getAllZipcodes(limitToken = 1000) {
  try {
    const response = await fetch(
      `${BASE_URL}/zipcodes/all?apikey=${API_KEY}&lang=en&limitToken=${limitToken}`
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error fetching zipcodes:', error);
    throw error;
  }
}

// Uso
const zipcodes = await getAllZipcodes(100);
console.log(zipcodes);

JavaScript (Axios)

import axios from 'axios';

const API_KEY = 'tu-clave-api';
const BASE_URL = 'https://api.countrydataapi.com/v1';

async function getAllZipcodes(limitToken = 1000) {
  try {
    const response = await axios.get(`${BASE_URL}/zipcodes/all`, {
      params: {
        apikey: API_KEY,
        lang: 'en',
        limitToken: limitToken
      }
    });

    return response.data;
  } catch (error) {
    console.error('Error fetching zipcodes:', error.response?.data || error.message);
    throw error;
  }
}

// Uso
const zipcodes = await getAllZipcodes(100);
console.log(zipcodes);

React

import { useState, useEffect } from 'react';

const API_KEY = 'tu-clave-api';
const BASE_URL = 'https://api.countrydataapi.com/v1';

function useAllZipcodes(limitToken = 1000) {
  const [zipcodes, setZipcodes] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchZipcodes() {
      try {
        setLoading(true);
        const response = await fetch(
          `${BASE_URL}/zipcodes/all?apikey=${API_KEY}&lang=en&limitToken=${limitToken}`
        );

        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        setZipcodes(data);
        setError(null);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    fetchZipcodes();
  }, [limitToken]);

  return { zipcodes, loading, error };
}

// Ejemplo de componente
function ZipcodeList() {
  const { zipcodes, loading, error } = useAllZipcodes(100);

  if (loading) return <div>Cargando códigos postales...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      <h2>Todos los Códigos Postales</h2>
      {zipcodes.map(country => (
        <div key={country.id}>
          <h3>{country.country_name}</h3>
          {country.state_names.map(state => (
            <div key={state.id}>
              <h4>{state.name}</h4>
              <p>{state.postal_code.join(', ')}</p>
            </div>
          ))}
        </div>
      ))}
    </div>
  );
}

export default ZipcodeList;

Vue 3

<script setup>
import { ref, onMounted } from 'vue';

const API_KEY = 'tu-clave-api';
const BASE_URL = 'https://api.countrydataapi.com/v1';

const zipcodes = ref([]);
const loading = ref(true);
const error = ref(null);

async function fetchAllZipcodes(limitToken = 1000) {
  try {
    loading.value = true;
    const response = await fetch(
      `${BASE_URL}/zipcodes/all?apikey=${API_KEY}&lang=en&limitToken=${limitToken}`
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    zipcodes.value = await response.json();
    error.value = null;
  } catch (err) {
    error.value = err.message;
  } finally {
    loading.value = false;
  }
}

onMounted(() => fetchAllZipcodes(100));
</script>

<template>
  <div>
    <div v-if="loading">Cargando códigos postales...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <div v-else>
      <h2>Todos los Códigos Postales</h2>
      <div v-for="country in zipcodes" :key="country.id">
        <h3>{{ country.country_name }}</h3>
        <div v-for="state in country.state_names" :key="state.id">
          <h4>{{ state.name }}</h4>
          <p>{{ state.postal_code.join(', ') }}</p>
        </div>
      </div>
    </div>
  </div>
</template>

Angular

// zipcode.service.ts
import { Injectable } from '@angular/core';
import { HttpClient, HttpParams } from '@angular/common/http';
import { Observable } from 'rxjs';

interface State {
  id: string;
  name: string;
  postal_code: string[];
}

interface ZipcodeResponse {
  id: string;
  country_name: string;
  state_names: State[];
}

@Injectable({
  providedIn: 'root'
})
export class ZipcodeService {
  private readonly API_KEY = 'tu-clave-api';
  private readonly BASE_URL = 'https://api.countrydataapi.com/v1';

  constructor(private http: HttpClient) {}

  getAllZipcodes(limitToken: number = 1000): Observable<ZipcodeResponse[]> {
    const params = new HttpParams()
      .set('apikey', this.API_KEY)
      .set('lang', 'en')
      .set('limitToken', limitToken.toString());

    return this.http.get<ZipcodeResponse[]>(
      `${this.BASE_URL}/zipcodes/all`,
      { params }
    );
  }
}

// zipcode-list.component.ts
import { Component, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ZipcodeService } from './zipcode.service';

@Component({
  selector: 'app-zipcode-list',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div *ngIf="loading">Cargando códigos postales...</div>
    <div *ngIf="error">Error: {{ error }}</div>
    <div *ngIf="!loading && !error">
      <h2>Todos los Códigos Postales</h2>
      <div *ngFor="let country of zipcodes">
        <h3>{{ country.country_name }}</h3>
        <div *ngFor="let state of country.state_names">
          <h4>{{ state.name }}</h4>
          <p>{{ state.postal_code.join(', ') }}</p>
        </div>
      </div>
    </div>
  `
})
export class ZipcodeListComponent implements OnInit {
  zipcodes: any[] = [];
  loading = true;
  error: string | null = null;

  constructor(private zipcodeService: ZipcodeService) {}

  ngOnInit() {
    this.zipcodeService.getAllZipcodes(100).subscribe({
      next: (data) => {
        this.zipcodes = data;
        this.loading = false;
      },
      error: (err) => {
        this.error = err.message;
        this.loading = false;
      }
    });
  }
}

PHP

<?php
$apiKey = 'tu-clave-api';
$limitToken = 100;
$url = "https://api.countrydataapi.com/v1/zipcodes/all?apikey={$apiKey}&lang=en&limitToken={$limitToken}";

// Usando cURL
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json'
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $zipcodes = json_decode($response, true);

    foreach ($zipcodes as $country) {
        echo "País: " . $country['country_name'] . "\n";
        foreach ($country['state_names'] as $state) {
            echo "  Estado: " . $state['name'] . "\n";
            echo "  Códigos Postales: " . implode(', ', $state['postal_code']) . "\n";
        }
    }
} else {
    echo "Error: HTTP {$httpCode}\n";
    echo $response;
}

// Alternativa usando file_get_contents
$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => 'Accept: application/json'
    ]
]);

$response = file_get_contents($url, false, $context);
$zipcodes = json_decode($response, true);
?>

Python

import requests
from typing import List, Dict, Any, Optional

API_KEY = 'tu-clave-api'
BASE_URL = 'https://api.countrydataapi.com/v1'

def get_all_zipcodes(limit_token: int = 1000, lang: str = 'en') -> List[Dict[str, Any]]:
    """
    Obtener todos los códigos postales de todos los países.

    Args:
        limit_token: Máximo de tokens a gastar en esta petición
        lang: Código de idioma para la respuesta

    Returns:
        Lista de países con sus códigos postales
    """
    try:
        response = requests.get(
            f'{BASE_URL}/zipcodes/all',
            params={
                'apikey': API_KEY,
                'lang': lang,
                'limitToken': limit_token
            },
            timeout=30
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Error fetching zipcodes: {e}')
        raise

# Uso
if __name__ == '__main__':
    zipcodes = get_all_zipcodes(limit_token=100)

    for country in zipcodes:
        print(f"País: {country['country_name']}")
        for state in country['state_names']:
            print(f"  Estado: {state['name']}")
            print(f"  Códigos Postales: {', '.join(state['postal_code'][:5])}...")

# Versión asíncrona con aiohttp
import aiohttp
import asyncio

async def get_all_zipcodes_async(limit_token: int = 1000) -> List[Dict[str, Any]]:
    """Versión asíncrona usando aiohttp"""
    async with aiohttp.ClientSession() as session:
        async with session.get(
            f'{BASE_URL}/zipcodes/all',
            params={
                'apikey': API_KEY,
                'lang': 'en',
                'limitToken': limit_token
            }
        ) as response:
            return await response.json()

# Ejecutar async
# zipcodes = asyncio.run(get_all_zipcodes_async(100))

Manejo de errores

Siempre implementa un manejo de errores adecuado en tu aplicación:

async function getAllZipcodesWithErrorHandling() {
  try {
    const response = await fetch(
      'https://api.countrydataapi.com/v1/zipcodes/all?apikey=tu-clave-api'
    );

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error('Clave API inválida');
      } else if (response.status === 429) {
        throw new Error('Límite de tasa excedido. Por favor intenta más tarde.');
      } else if (response.status === 402) {
        throw new Error('Tokens insuficientes. Por favor actualiza tu plan.');
      }
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    if (!Array.isArray(data)) {
      throw new Error('Formato de respuesta inválido');
    }

    return data;
  } catch (error) {
    console.error('Error al obtener códigos postales:', error.message);
    // Maneja el error apropiadamente (mostrar mensaje al usuario, reintentar, etc.)
    throw error;
  }
}

Códigos de error comunes

Código de Error	Descripción	Solución
`INVALID_API_KEY`	La clave API es inválida	Verifica tu clave API en el panel de cuenta
`QUOTA_EXCEEDED`	Límite diario de tokens alcanzado	Actualiza tu plan o espera el reinicio
`RATE_LIMITED`	Demasiadas peticiones	Implementa limitación de tasa en tu app
`INVALID_LANGUAGE`	Código de idioma no soportado	Usa uno de los códigos de idioma soportados

Consejos de rendimiento

Usa limitToken: Controla la cantidad de datos devueltos para gestionar costos
Cachea los resultados: Los códigos postales no cambian frecuentemente; cachea por 24+ horas
Pagina: Para conjuntos de datos grandes, usa múltiples peticiones con diferentes límites
Filtra del lado del cliente: Si solo necesitas datos específicos, filtra después de obtenerlos

Límites de tasa

Tier gratuito: 100 peticiones/día
Tier básico: 1,000 peticiones/día
Tier pro: 10,000 peticiones/día
Tier empresarial: Ilimitado

Consulta nuestra página de precios para más detalles.

Endpoints relacionados

GET /v1/zipcodes/state - Obtener códigos postales por estado
GET /v1/zipcodes/country - Obtener códigos postales por país
GET /v1/zipcodes/region - Obtener códigos postales por región

¿Necesitas ayuda?

Consulta nuestra documentación de códigos de error
Ve la guía de autenticación
Contacta soporte a través de tu panel de cuenta

Documentación de la API - Endpoints y Ejemplos

Todos los códigos postales