Documentación de la API - Endpoints y Ejemplos

Descripción general

Este endpoint devuelve una lista de todas las ciudades disponibles en la base de datos de CountryDataAPI. Proporciona un listado global de ciudades, lo que lo hace ideal para aplicaciones que necesitan mostrar o buscar datos a nivel de ciudad en todo el mundo.

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

Autenticación

Todas las solicitudes a la API requieren autenticación mediante una clave API. Incluye tu clave API como parámetro de consulta en cada solicitud:

?apikey=TU_CLAVE_API

Puedes obtener una clave API registrándote en CountryDataAPI.

Petición

HTTP GET

https://api.countrydataapi.com/v1/cities/all

Retorna una lista de todas las ciudades

Cada 5 ciudades retornadas consumirá 1 token

Parámetros de consulta

Respuesta

Ejemplo de respuesta

[
  {
    "id": "d54ba796-1136-4776-9776-537fd5a857c9",
    "lang": "en",
    "city_name": "Bala Morghab"
  }
]

Ejemplos de código

JavaScript (Fetch)

const API_KEY = 'TU_CLAVE_API';
const BASE_URL = 'https://api.countrydataapi.com/v1/cities/all';

async function getAllCities(limit = 100) {
  try {
    const params = new URLSearchParams({
      apikey: API_KEY,
      lang: 'en',
      limit: limit.toString()
    });

    const response = await fetch(`${BASE_URL}?${params}`);

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

    const cities = await response.json();
    console.log(`Retrieved ${cities.length} cities`);
    return cities;
  } catch (error) {
    console.error('Error fetching cities:', error);
    throw error;
  }
}

// Uso
getAllCities(50);  // Obtener las primeras 50 ciudades
getAllCities(200); // Obtener las primeras 200 ciudades

JavaScript (Axios)

import axios from 'axios';

const API_KEY = 'TU_CLAVE_API';
const BASE_URL = 'https://api.countrydataapi.com/v1/cities/all';

async function getAllCities(limit = 100) {
  try {
    const response = await axios.get(BASE_URL, {
      params: {
        apikey: API_KEY,
        lang: 'en',
        limit: limit
      }
    });

    console.log(`Retrieved ${response.data.length} cities`);
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      console.error('API Error:', error.response?.data || error.message);
    }
    throw error;
  }
}

// Uso
getAllCities(100);

React

import { useState, useEffect } from 'react';

const API_KEY = 'TU_CLAVE_API';
const BASE_URL = 'https://api.countrydataapi.com/v1/cities/all';

function CitiesList({ limit = 100 }) {
  const [cities, setCities] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchCities = async () => {
      try {
        setLoading(true);
        const params = new URLSearchParams({
          apikey: API_KEY,
          lang: 'en',
          limit: limit.toString()
        });

        const response = await fetch(`${BASE_URL}?${params}`);

        if (!response.ok) {
          throw new Error('Failed to fetch cities');
        }

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

    fetchCities();
  }, [limit]);

  if (loading) return <div>Cargando ciudades...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      <h2>Todas las Ciudades</h2>
      <p>Mostrando {cities.length} ciudades</p>
      <ul>
        {cities.map((city) => (
          <li key={city.id}>{city.city_name}</li>
        ))}
      </ul>
    </div>
  );
}

// Búsqueda de ciudades con paginación
function CitiesWithPagination() {
  const [cities, setCities] = useState([]);
  const [page, setPage] = useState(1);
  const [loading, setLoading] = useState(false);
  const pageSize = 50;

  const loadCities = async () => {
    setLoading(true);
    const params = new URLSearchParams({
      apikey: API_KEY,
      lang: 'en',
      limit: (page * pageSize).toString()
    });

    try {
      const response = await fetch(`${BASE_URL}?${params}`);
      const data = await response.json();
      setCities(data);
    } catch (err) {
      console.error(err);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    loadCities();
  }, [page]);

  return (
    <div>
      <h2>Ciudades ({cities.length})</h2>
      <ul>
        {cities.map((city) => (
          <li key={city.id}>{city.city_name}</li>
        ))}
      </ul>
      <button
        onClick={() => setPage(p => p + 1)}
        disabled={loading}
      >
        {loading ? 'Cargando...' : 'Cargar más'}
      </button>
    </div>
  );
}

export default CitiesList;

Vue 3

<template>
  <div>
    <div v-if="loading">Cargando ciudades...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <div v-else>
      <h2>Todas las Ciudades</h2>
      <p>Mostrando {{ cities.length }} ciudades</p>
      <ul>
        <li v-for="city in cities" :key="city.id">
          {{ city.city_name }}
        </li>
      </ul>
    </div>
  </div>
</template>

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

const props = defineProps({
  limit: {
    type: Number,
    default: 100
  }
});

const API_KEY = 'TU_CLAVE_API';
const BASE_URL = 'https://api.countrydataapi.com/v1/cities/all';

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

const fetchCities = async () => {
  try {
    loading.value = true;
    error.value = null;

    const params = new URLSearchParams({
      apikey: API_KEY,
      lang: 'en',
      limit: props.limit.toString()
    });

    const response = await fetch(`${BASE_URL}?${params}`);

    if (!response.ok) {
      throw new Error('Failed to fetch cities');
    }

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

watch(() => props.limit, fetchCities);
onMounted(fetchCities);
</script>

Angular

import { Component, Input, OnInit, OnChanges } from '@angular/core';
import { HttpClient, HttpParams } from '@angular/common/http';
import { CommonModule } from '@angular/common';

interface City {
  id: string;
  city_name: string;
  lang: string;
}

@Component({
  selector: 'app-cities-list',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div>
      <div *ngIf="loading">Cargando ciudades...</div>
      <div *ngIf="error">Error: {{ error }}</div>
      <div *ngIf="!loading && !error">
        <h2>Todas las Ciudades</h2>
        <p>Mostrando {{ cities.length }} ciudades</p>
        <ul>
          <li *ngFor="let city of cities">{{ city.city_name }}</li>
        </ul>
      </div>
    </div>
  `
})
export class CitiesListComponent implements OnInit, OnChanges {
  @Input() limit = 100;

  private readonly API_KEY = 'TU_CLAVE_API';
  private readonly BASE_URL = 'https://api.countrydataapi.com/v1/cities/all';

  cities: City[] = [];
  loading = true;
  error: string | null = null;

  constructor(private http: HttpClient) {}

  ngOnInit(): void {
    this.fetchCities();
  }

  ngOnChanges(): void {
    this.fetchCities();
  }

  private fetchCities(): void {
    this.loading = true;
    this.error = null;

    const params = new HttpParams()
      .set('apikey', this.API_KEY)
      .set('lang', 'en')
      .set('limit', this.limit.toString());

    this.http.get<City[]>(this.BASE_URL, { params }).subscribe({
      next: (data) => {
        this.cities = data;
        this.loading = false;
      },
      error: (err) => {
        this.error = err.message;
        this.loading = false;
      }
    });
  }
}

PHP

<?php

$apiKey = 'TU_CLAVE_API';
$baseUrl = 'https://api.countrydataapi.com/v1/cities/all';

function getAllCities($limit, $apiKey) {
    $baseUrl = 'https://api.countrydataapi.com/v1/cities/all';

    $params = http_build_query([
        'apikey' => $apiKey,
        'lang' => 'en',
        'limit' => $limit
    ]);

    $url = $baseUrl . '?' . $params;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

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

    if ($httpCode !== 200) {
        throw new Exception("HTTP Error: $httpCode");
    }

    return json_decode($response, true);
}

// Uso
try {
    $cities = getAllCities(100, $apiKey);

    echo "Obtenidas " . count($cities) . " ciudades\n\n";

    foreach ($cities as $city) {
        echo "- " . $city['city_name'] . " (ID: " . $city['id'] . ")\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

// Calcular uso de tokens
function calculateTokenUsage($cityCount) {
    return ceil($cityCount / 5);
}

$limit = 100;
$cities = getAllCities($limit, $apiKey);
echo "Ciudades obtenidas: " . count($cities) . "\n";
echo "Tokens consumidos: " . calculateTokenUsage(count($cities)) . "\n";
?>

Python

import requests

API_KEY = 'TU_CLAVE_API'
BASE_URL = 'https://api.countrydataapi.com/v1/cities/all'

def get_all_cities(limit=100):
    """Obtener todas las ciudades de CountryDataAPI."""
    params = {
        'apikey': API_KEY,
        'lang': 'en',
        'limit': limit
    }

    try:
        response = requests.get(BASE_URL, params=params)
        response.raise_for_status()

        cities = response.json()
        return cities
    except requests.exceptions.RequestException as e:
        print(f'Error fetching cities: {e}')
        raise

def calculate_token_usage(city_count):
    """Calcular tokens consumidos (5 ciudades = 1 token)."""
    return (city_count + 4) // 5  # División con redondeo hacia arriba

# Uso
if __name__ == '__main__':
    limit = 100
    cities = get_all_cities(limit)

    print(f"Obtenidas {len(cities)} ciudades")
    print(f"Tokens consumidos: {calculate_token_usage(len(cities))}")
    print("\nPrimeras 10 ciudades:")

    for city in cities[:10]:
        print(f"  - {city['city_name']}")


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

async def get_all_cities_async(limit=100):
    """Obtener todas las ciudades de forma asíncrona."""
    params = {
        'apikey': API_KEY,
        'lang': 'en',
        'limit': limit
    }

    async with aiohttp.ClientSession() as session:
        async with session.get(BASE_URL, params=params) as response:
            if response.status == 200:
                return await response.json()
            else:
                raise Exception(f'HTTP Error: {response.status}')

# Uso
# cities = asyncio.run(get_all_cities_async(200))

cURL

# Obtener las primeras 100 ciudades (predeterminado)
curl -X GET "https://api.countrydataapi.com/v1/cities/all?apikey=TU_CLAVE_API&lang=en"

# Obtener las primeras 50 ciudades
curl -X GET "https://api.countrydataapi.com/v1/cities/all?apikey=TU_CLAVE_API&lang=en&limit=50"

# Obtener 200 ciudades
curl -X GET "https://api.countrydataapi.com/v1/cities/all?apikey=TU_CLAVE_API&lang=en&limit=200"

# Con salida JSON formateada
curl -X GET "https://api.countrydataapi.com/v1/cities/all?apikey=TU_CLAVE_API&lang=en&limit=100" | json_pp

# Guardar respuesta en archivo
curl -X GET "https://api.countrydataapi.com/v1/cities/all?apikey=TU_CLAVE_API&lang=en&limit=500" -o all_cities.json

# Obtener ciudades en español
curl -X GET "https://api.countrydataapi.com/v1/cities/all?apikey=TU_CLAVE_API&lang=es&limit=100"

Manejo de errores

La API puede devolver las siguientes respuestas de error:

Ejemplo de respuesta de error

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Consumo de tokens

Cada 5 ciudades retornadas consumirá 1 token. Por ejemplo:

• 50 ciudades = 10 tokens
• 100 ciudades = 20 tokens
• 500 ciudades = 100 tokens

Planifica tus solicitudes en consecuencia para optimizar el uso de tokens.