<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet" /> <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" />
Country Data API

Obtener Países para Select

Obtén todos los países optimizados para dropdowns y formularios

El endpoint /v1/select/countries devuelve una lista ligera de todos los países con solo los campos id y name, optimizada para menús desplegables e inputs de formularios.

Endpoint

GET https://api.countrydataapi.com/v1/select/countries

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 nombres de países (por defecto: en)

Idiomas Soportados

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

Ejemplo de Solicitud

curl "https://api.countrydataapi.com/v1/select/countries?apikey=tu-clave-api&lang=es"

JavaScript (Fetch)

const API_KEY = 'tu-clave-api';

async function loadCountries() {
  const response = await fetch(
    `https://api.countrydataapi.com/v1/select/countries?apikey=${API_KEY}&lang=es`
  );
  const data = await response.json();
  return data;
}

JavaScript (Axios)

import axios from 'axios';

const response = await axios.get(
  'https://api.countrydataapi.com/v1/select/countries',
  {
    params: {
      apikey: 'tu-clave-api',
      lang: 'es',
    },
  }
);

Python

import requests

response = requests.get(
    'https://api.countrydataapi.com/v1/select/countries',
    params={
        'apikey': 'tu-clave-api',
        'lang': 'es'
    }
)
data = response.json()

PHP

<?php
$apiKey = 'tu-clave-api';
$url = "https://api.countrydataapi.com/v1/select/countries?apikey={$apiKey}&lang=es";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
?>

Angular

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

interface Country {
  id: string;
  name: string;
}

interface ApiResponse {
  success: boolean;
  data: Country[];
}

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

  constructor(private http: HttpClient) {}

  getCountries(lang: string = 'es'): Observable<Country[]> {
    const params = new HttpParams()
      .set('apikey', this.API_KEY)
      .set('lang', lang);

    return this.http.get<ApiResponse>(
      `${this.BASE_URL}/select/countries`,
      { params }
    ).pipe(
      map(response => response.data)
    );
  }
}

// country-select.component.ts
import { Component, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';
import { FormsModule } from '@angular/forms';
import { CountryService } from './country.service';

@Component({
  selector: 'app-country-select',
  standalone: true,
  imports: [CommonModule, FormsModule],
  template: `
    <div *ngIf="loading">Cargando países...</div>
    <div *ngIf="error" class="error">{{ error }}</div>
    <select
      *ngIf="!loading && !error"
      [(ngModel)]="selectedCountry"
      (ngModelChange)="onCountryChange($event)"
    >
      <option value="">Selecciona un país...</option>
      <option *ngFor="let country of countries" [value]="country.id">
        {{ country.name }}
      </option>
    </select>
  `
})
export class CountrySelectComponent implements OnInit {
  countries: any[] = [];
  selectedCountry = '';
  loading = true;
  error: string | null = null;

  constructor(private countryService: CountryService) {}

  ngOnInit() {
    this.countryService.getCountries('es').subscribe({
      next: (data) => {
        this.countries = data;
        this.loading = false;
      },
      error: (err) => {
        this.error = 'Error al cargar países';
        this.loading = false;
      }
    });
  }

  onCountryChange(countryId: string) {
    console.log('País seleccionado:', countryId);
    // Disparar carga de estados, emitir evento, etc.
  }
}

Formato de Respuesta

Respuesta Exitosa

{
  "success": true,
  "data": [
    {
      "id": "66c7a6c9e4bda21f4ab10ef2",
      "name": "Afganistán"
    },
    {
      "id": "66c7a6c9e4bda21f4ab10ef3",
      "name": "Albania"
    },
    {
      "id": "66c7a6c9e4bda21f4ab10ef4",
      "name": "Argelia"
    }
    // ... más países (200+ en total)
  ]
}

Campos de Respuesta

Campo Tipo Descripción
success boolean Indica si la solicitud fue exitosa
data array Array de objetos de país
data[].id string Identificador único del país (MongoDB ObjectId)
data[].name string Nombre del país en el idioma solicitado

Respuesta de Error

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "La clave API proporcionada es inválida"
  }
}

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

Tamaño de Respuesta

El endpoint select está optimizado para ancho de banda mínimo:

  • Endpoint completo (/v1/countries/all): ~500KB (incluye todos los datos del país)
  • Endpoint select (/v1/select/countries): ~15KB (solo id y name)

¡Esto hace que el endpoint select sea 97% más pequeño y perfecto para dropdowns de formularios!

Uso de Tokens

Este endpoint consume 1 token por solicitud.

Consejo: Cachea la respuesta en localStorage o el estado de tu aplicación. Los países rara vez cambian, así que puedes cachear de forma segura durante 7+ días.

Casos de Uso

1. Menú Desplegable

<select id="country">
  <option value="">Selecciona país...</option>
  <!-- Poblado via JavaScript -->
</select>

<script>
async function populateCountries() {
  const response = await fetch(
    'https://api.countrydataapi.com/v1/select/countries?apikey=tu-clave-api&lang=es'
  );
  const { data } = await response.json();

  const select = document.getElementById('country');
  data.forEach(country => {
    const option = new Option(country.name, country.id);
    select.add(option);
  });
}

populateCountries();
</script>

2. Componente React

import { useState, useEffect } from 'react';

function CountrySelect() {
  const [countries, setCountries] = useState([]);

  useEffect(() => {
    fetch('https://api.countrydataapi.com/v1/select/countries?apikey=tu-clave-api&lang=es')
      .then(res => res.json())
      .then(({ data }) => setCountries(data));
  }, []);

  return (
    <select>
      <option value="">Selecciona país...</option>
      {countries.map(country => (
        <option key={country.id} value={country.id}>
          {country.name}
        </option>
      ))}
    </select>
  );
}

3. Componente Vue

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

const countries = ref([]);

onMounted(async () => {
  const response = await fetch(
    'https://api.countrydataapi.com/v1/select/countries?apikey=tu-clave-api&lang=es'
  );
  const { data } = await response.json();
  countries.value = data;
});
</script>

<template>
  <select>
    <option value="">Selecciona país...</option>
    <option v-for="country in countries" :key="country.id" :value="country.id">
      {{ country.name }}
    </option>
  </select>
</template>

Ejemplo de Caché

Cachea países en localStorage para minimizar llamadas API:

const CACHE_KEY = 'countries_cache';
const CACHE_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 días

async function getCountries() {
  // Verificar caché primero
  const cached = localStorage.getItem(CACHE_KEY);
  if (cached) {
    const { data, timestamp } = JSON.parse(cached);
    if (Date.now() - timestamp < CACHE_DURATION) {
      return data;
    }
  }

  // Obtener de la API
  const response = await fetch(
    'https://api.countrydataapi.com/v1/select/countries?apikey=tu-clave-api&lang=es'
  );
  const { data } = await response.json();

  // Guardar en caché
  localStorage.setItem(CACHE_KEY, JSON.stringify({
    data,
    timestamp: Date.now()
  }));

  return data;
}

Ejemplo Multi-idioma

Cambia entre idiomas dinámicamente:

function loadCountries(language = 'es') {
  return fetch(
    `https://api.countrydataapi.com/v1/select/countries?apikey=tu-clave-api&lang=${language}`
  ).then(res => res.json());
}

// Cargar en español
const spanishCountries = await loadCountries('es');

// Cargar en francés
const frenchCountries = await loadCountries('fr');

Consejos de Rendimiento

  1. Cachea agresivamente: Los países no cambian a menudo
  2. Usa carga perezosa: Carga países cuando el dropdown tenga foco
  3. Implementa búsqueda: Para mejor UX con 200+ países
  4. Precarga al cargar página: Obtén en segundo plano mientras el usuario lee contenido

Límites de Tasa

  • Tier gratuito: 100 solicitudes/día
  • Tier básico: 1,000 solicitudes/día
  • Tier pro: 10,000 solicitudes/día
  • Tier enterprise: Ilimitado

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

Endpoints Relacionados

Guías de Integración Completas

¿Necesitas Ayuda?

Nota: El campo id devuelto es un ObjectId de MongoDB que identifica de forma única cada país en todos los endpoints. Usa este ID cuando consultes estados, ciudades u otros datos relacionados.