Documentación de la API - Endpoints y Ejemplos

Descripcion general

Este endpoint devuelve una lista completa de todos los estados disponibles en la base de datos de CountryDataAPI. Proporciona información detallada sobre estados de todo el mundo, lo que lo hace ideal para aplicaciones que necesitan mostrar o procesar datos geográficos a nivel estatal.

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/state/all

Retorna una lista de todos los estados

Según los campos solicitados, habrá 3 tipos de peticiones:

• BASIC: Retorna los campos id, state_name, lang Cada estado costará 1 token

• NORMAL: Retorna el campo state_cities [Todos los IDs y nombres de ciudades del estado] Cada ciudad costará 1 token

• ADVANCED: Retorna el campo state_zip_codes [Todos los códigos postales de la ciudad] Cada código postal cuesta 1 token

Parámetros de consulta

Respuesta

Ejemplo de respuesta

[
  {
    "id": "8dd25479-067a-43b0-ac4a-8e7faf2bcafb",
    "state_name": "Takhar",
    "lang": "en",
    "state_cities": [
      {
        "id": "8dd25476-067a-43b0-ac4b-8e7faf2bcbfb",
        "city_name": "City"
      }
    ],
    "state_zip_codes": [
      "00000",
      "00001"
    ]
  }
]

Ejemplos de código

JavaScript (Fetch)

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

async function getAllStates() {
  try {
    const params = new URLSearchParams({
      apikey: API_KEY,
      lang: 'en',
      limitStates: '10',
      fields: 'id,state_name,lang'
    });

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

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

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

// Uso
getAllStates();

JavaScript (Axios)

import axios from 'axios';

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

async function getAllStates() {
  try {
    const response = await axios.get(BASE_URL, {
      params: {
        apikey: API_KEY,
        lang: 'en',
        limitStates: 10,
        fields: 'id,state_name,lang'
      }
    });

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

// Uso
getAllStates();

React

import { useState, useEffect } from 'react';

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

function StatesList() {
  const [states, setStates] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchStates = async () => {
      try {
        const params = new URLSearchParams({
          apikey: API_KEY,
          lang: 'en',
          limitStates: '10',
          fields: 'id,state_name,lang'
        });

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

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

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

    fetchStates();
  }, []);

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

  return (
    <div>
      <h2>Todos los Estados</h2>
      <ul>
        {states.map((state) => (
          <li key={state.id}>{state.state_name}</li>
        ))}
      </ul>
    </div>
  );
}

export default StatesList;

Vue 3

<template>
  <div>
    <h2>Todos los Estados</h2>
    <div v-if="loading">Cargando estados...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <ul v-else>
      <li v-for="state in states" :key="state.id">
        {{ state.state_name }}
      </li>
    </ul>
  </div>
</template>

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

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

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

const fetchStates = async () => {
  try {
    const params = new URLSearchParams({
      apikey: API_KEY,
      lang: 'en',
      limitStates: '10',
      fields: 'id,state_name,lang'
    });

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

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

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

onMounted(fetchStates);
</script>

Angular

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

interface State {
  id: string;
  state_name: string;
  lang: string;
  state_cities?: Array<{ id: string; city_name: string }>;
  state_zip_codes?: string[];
}

@Component({
  selector: 'app-states-list',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div>
      <h2>Todos los Estados</h2>
      <div *ngIf="loading">Cargando estados...</div>
      <div *ngIf="error">Error: {{ error }}</div>
      <ul *ngIf="!loading && !error">
        <li *ngFor="let state of states">{{ state.state_name }}</li>
      </ul>
    </div>
  `
})
export class StatesListComponent implements OnInit {
  private readonly API_KEY = 'TU_CLAVE_API';
  private readonly BASE_URL = 'https://api.countrydataapi.com/v1/state/all';

  states: State[] = [];
  loading = true;
  error: string | null = null;

  constructor(private http: HttpClient) {}

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

  private fetchStates(): void {
    const params = new HttpParams()
      .set('apikey', this.API_KEY)
      .set('lang', 'en')
      .set('limitStates', '10')
      .set('fields', 'id,state_name,lang');

    this.http.get<State[]>(this.BASE_URL, { params }).subscribe({
      next: (data) => {
        this.states = 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/state/all';

$params = http_build_query([
    'apikey' => $apiKey,
    'lang' => 'en',
    'limitStates' => 10,
    'fields' => 'id,state_name,lang'
]);

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

$options = [
    'http' => [
        'method' => 'GET',
        'header' => 'Content-Type: application/json'
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);

if ($response === false) {
    die('Error fetching states');
}

$states = json_decode($response, true);

foreach ($states as $state) {
    echo "State: " . $state['state_name'] . "\n";
}

// Usando cURL
function getAllStatesWithCurl($apiKey) {
    $baseUrl = 'https://api.countrydataapi.com/v1/state/all';

    $params = http_build_query([
        'apikey' => $apiKey,
        'lang' => 'en',
        'limitStates' => 10,
        'fields' => 'id,state_name,lang'
    ]);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . '?' . $params);
    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);
}
?>

Python

import requests

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

def get_all_states():
    """Obtener todos los estados de CountryDataAPI."""
    params = {
        'apikey': API_KEY,
        'lang': 'en',
        'limitStates': 10,
        'fields': 'id,state_name,lang'
    }

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

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

# Uso
if __name__ == '__main__':
    states = get_all_states()
    for state in states:
        print(f"State: {state['state_name']}")


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

async def get_all_states_async():
    """Obtener todos los estados de forma asíncrona."""
    params = {
        'apikey': API_KEY,
        'lang': 'en',
        'limitStates': 10,
        'fields': 'id,state_name,lang'
    }

    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
# asyncio.run(get_all_states_async())

cURL

# Petición básica
curl -X GET "https://api.countrydataapi.com/v1/state/all?apikey=TU_CLAVE_API&lang=en&limitStates=10&fields=id,state_name,lang"

# Con salida JSON formateada
curl -X GET "https://api.countrydataapi.com/v1/state/all?apikey=TU_CLAVE_API&lang=en&limitStates=10&fields=id,state_name,lang" | json_pp

# Con headers mostrados
curl -v -X GET "https://api.countrydataapi.com/v1/state/all?apikey=TU_CLAVE_API&lang=en&limitStates=10"

# Guardar respuesta en archivo
curl -X GET "https://api.countrydataapi.com/v1/state/all?apikey=TU_CLAVE_API&lang=en&limitStates=10" -o states.json

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"
}