Name: CountryDataAPI
Rating: 4.8 (150 reviews)
Author: CountryDataAPI

Descripcion general

Este endpoint recupera datos completos de un estado específico, incluyendo todas las ciudades y códigos postales dentro de ese estado. Úsalo cuando necesites información detallada sobre un estado particular por su ID o nombre.

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/states

Retorna todos los datos de ese estado.

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

Parámetro	Tipo	Descripción
apikey	requerido, token	Clave de autenticación de la cuenta
state	requerido, id o string	ID del estado o nombre del estado
limitToken	opcional, number	1000 (predeterminado). Número máximo de tokens que quieres gastar en esta petición
fields	opcional, string	id,lang,state_name (predeterminado). Campos esperados en la respuesta
lang	opcional, lang	en (predeterminado). Idioma esperado de la respuesta

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/states';

async function getStateData(stateName) {
  try {
    const params = new URLSearchParams({
      apikey: API_KEY,
      state: stateName,
      lang: 'en',
      fields: 'id,state_name,lang,state_cities'
    });

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

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

    const stateData = await response.json();
    console.log('State Data:', stateData);
    return stateData;
  } catch (error) {
    console.error('Error fetching state data:', error);
    throw error;
  }
}

// Uso
getStateData('California');
// O por ID
getStateData('8dd25479-067a-43b0-ac4a-8e7faf2bcafb');

JavaScript (Axios)

import axios from 'axios';

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

async function getStateData(stateName) {
  try {
    const response = await axios.get(BASE_URL, {
      params: {
        apikey: API_KEY,
        state: stateName,
        lang: 'en',
        fields: 'id,state_name,lang,state_cities'
      }
    });

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

// Uso
getStateData('Texas');

React

import { useState, useEffect } from 'react';

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

function StateDetails({ stateName }) {
  const [stateData, setStateData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchStateData = async () => {
      if (!stateName) return;

      try {
        setLoading(true);
        const params = new URLSearchParams({
          apikey: API_KEY,
          state: stateName,
          lang: 'en',
          fields: 'id,state_name,lang,state_cities'
        });

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

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

        const data = await response.json();
        setStateData(data[0]);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    fetchStateData();
  }, [stateName]);

  if (loading) return <div>Cargando datos del estado...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!stateData) return <div>No se encontraron datos</div>;

  return (
    <div>
      <h2>{stateData.state_name}</h2>
      <p>ID: {stateData.id}</p>
      {stateData.state_cities && (
        <div>
          <h3>Ciudades ({stateData.state_cities.length})</h3>
          <ul>
            {stateData.state_cities.map((city) => (
              <li key={city.id}>{city.city_name}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

export default StateDetails;

Vue 3

<template>
  <div>
    <div v-if="loading">Cargando datos del estado...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <div v-else-if="stateData">
      <h2>{{ stateData.state_name }}</h2>
      <p>ID: {{ stateData.id }}</p>
      <div v-if="stateData.state_cities">
        <h3>Ciudades ({{ stateData.state_cities.length }})</h3>
        <ul>
          <li v-for="city in stateData.state_cities" :key="city.id">
            {{ city.city_name }}
          </li>
        </ul>
      </div>
    </div>
    <div v-else>No se encontraron datos</div>
  </div>
</template>

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

const props = defineProps({
  stateName: {
    type: String,
    required: true
  }
});

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

const stateData = ref(null);
const loading = ref(true);
const error = ref(null);

const fetchStateData = async () => {
  if (!props.stateName) return;

  try {
    loading.value = true;
    error.value = null;

    const params = new URLSearchParams({
      apikey: API_KEY,
      state: props.stateName,
      lang: 'en',
      fields: 'id,state_name,lang,state_cities'
    });

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

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

    const data = await response.json();
    stateData.value = data[0];
  } catch (err) {
    error.value = err.message;
  } finally {
    loading.value = false;
  }
};

watch(() => props.stateName, fetchStateData);
onMounted(fetchStateData);
</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;
}

interface State {
  id: string;
  state_name: string;
  lang: string;
  state_cities?: City[];
  state_zip_codes?: string[];
}

@Component({
  selector: 'app-state-details',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div>
      <div *ngIf="loading">Cargando datos del estado...</div>
      <div *ngIf="error">Error: {{ error }}</div>
      <div *ngIf="!loading && !error && stateData">
        <h2>{{ stateData.state_name }}</h2>
        <p>ID: {{ stateData.id }}</p>
        <div *ngIf="stateData.state_cities">
          <h3>Ciudades ({{ stateData.state_cities.length }})</h3>
          <ul>
            <li *ngFor="let city of stateData.state_cities">
              {{ city.city_name }}
            </li>
          </ul>
        </div>
      </div>
    </div>
  `
})
export class StateDetailsComponent implements OnInit, OnChanges {
  @Input() stateName!: string;

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

  stateData: State | null = null;
  loading = true;
  error: string | null = null;

  constructor(private http: HttpClient) {}

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

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

  private fetchStateData(): void {
    if (!this.stateName) return;

    this.loading = true;
    this.error = null;

    const params = new HttpParams()
      .set('apikey', this.API_KEY)
      .set('state', this.stateName)
      .set('lang', 'en')
      .set('fields', 'id,state_name,lang,state_cities');

    this.http.get<State[]>(this.BASE_URL, { params }).subscribe({
      next: (data) => {
        this.stateData = data[0] || null;
        this.loading = false;
      },
      error: (err) => {
        this.error = err.message;
        this.loading = false;
      }
    });
  }
}

PHP

<?php

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

function getStateData($stateName, $apiKey) {
    $baseUrl = 'https://api.countrydataapi.com/v1/states';

    $params = http_build_query([
        'apikey' => $apiKey,
        'state' => $stateName,
        'lang' => 'en',
        'fields' => 'id,state_name,lang,state_cities'
    ]);

    $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 {
    $stateData = getStateData('California', $apiKey);

    if (!empty($stateData)) {
        $state = $stateData[0];
        echo "Estado: " . $state['state_name'] . "\n";
        echo "ID: " . $state['id'] . "\n";

        if (isset($state['state_cities'])) {
            echo "Ciudades:\n";
            foreach ($state['state_cities'] as $city) {
                echo "  - " . $city['city_name'] . "\n";
            }
        }
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Python

import requests

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

def get_state_data(state_name):
    """Obtener datos detallados de un estado específico."""
    params = {
        'apikey': API_KEY,
        'state': state_name,
        'lang': 'en',
        'fields': 'id,state_name,lang,state_cities'
    }

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

        state_data = response.json()
        return state_data[0] if state_data else None
    except requests.exceptions.RequestException as e:
        print(f'Error fetching state data: {e}')
        raise

# Uso
if __name__ == '__main__':
    state = get_state_data('California')

    if state:
        print(f"Estado: {state['state_name']}")
        print(f"ID: {state['id']}")

        if 'state_cities' in state:
            print(f"Ciudades ({len(state['state_cities'])}):")
            for city in state['state_cities'][:5]:  # Primeras 5 ciudades
                print(f"  - {city['city_name']}")


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

async def get_state_data_async(state_name):
    """Obtener datos del estado de forma asíncrona."""
    params = {
        'apikey': API_KEY,
        'state': state_name,
        'lang': 'en',
        'fields': 'id,state_name,lang,state_cities'
    }

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

# Uso
# state = asyncio.run(get_state_data_async('Texas'))

cURL

# Petición básica por nombre de estado
curl -X GET "https://api.countrydataapi.com/v1/states?apikey=TU_CLAVE_API&state=California&lang=en&fields=id,state_name,lang,state_cities"

# Petición por ID de estado
curl -X GET "https://api.countrydataapi.com/v1/states?apikey=TU_CLAVE_API&state=8dd25479-067a-43b0-ac4a-8e7faf2bcafb&lang=en"

# Con salida JSON formateada
curl -X GET "https://api.countrydataapi.com/v1/states?apikey=TU_CLAVE_API&state=Texas&lang=en" | json_pp

# Incluir códigos postales (petición ADVANCED)
curl -X GET "https://api.countrydataapi.com/v1/states?apikey=TU_CLAVE_API&state=Colorado&fields=id,state_name,state_cities,state_zip_codes"

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

Manejo de errores

La API puede devolver las siguientes respuestas de error:

Código de estado	Descripción
400	Bad Request - Parámetros inválidos o estado faltante
401	Unauthorized - Clave API inválida o faltante
403	Forbidden - Permisos insuficientes o saldo de tokens
404	Not Found - Estado no encontrado
429	Too Many Requests - Límite de tasa excedido
500	Internal Server Error

Ejemplo de respuesta de error

{
  "statusCode": 404,
  "message": "State not found",
  "error": "Not Found"
}

Documentación de la API - Endpoints y Ejemplos

Todos los datos de un estado