Obtenez les régions/provinces par pays, optimisées pour les listes déroulantes

L'endpoint /v1/select/states retourne une liste légère de régions/provinces filtrées par pays, avec uniquement les champs id et name, optimisée pour les menus déroulants.

Endpoint

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

Authentification

Incluez votre clé API comme paramètre de requête :

?apikey=votre-cle-api

Votre clé API est comme un mot de passe, gardez-la sécurisée. Obtenez votre clé depuis le tableau de bord de votre compte.

Paramètres de Requête

Paramètre	Type	Requis	Description
`apikey`	string	Oui	Votre clé d'authentification API
`country`	string	Oui	ID du pays (depuis l'endpoint `/select/countries`)
`lang`	string	Non	Code de langue pour les noms de régions (défaut : `en`)

Langues Supportées

en - Anglais (défaut)
es - Espagnol
pt - Portugais
fr - Français
de - Allemand
it - Italien

Exemple de Requête

# Obtenir les régions de France
curl "https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=66c7a6c9e4bda21f4ab10f1b&lang=fr"

JavaScript (Fetch)

const API_KEY = 'votre-cle-api';
const COUNTRY_ID = '66c7a6c9e4bda21f4ab10f1b'; // France

async function chargerRegions(countryId) {
  const response = await fetch(
    `https://api.countrydataapi.com/v1/select/states?apikey=${API_KEY}&country=${countryId}&lang=fr`
  );
  const data = await response.json();
  return data;
}

const régions = await chargerRegions(COUNTRY_ID);

JavaScript (Axios)

import axios from 'axios';

const response = await axios.get(
  'https://api.countrydataapi.com/v1/select/states',
  {
    params: {
      apikey: 'votre-cle-api',
      country: '66c7a6c9e4bda21f4ab10f1b',
      lang: 'fr',
    },
  }
);

Python

import requests

response = requests.get(
    'https://api.countrydataapi.com/v1/select/states',
    params={
        'apikey': 'votre-cle-api',
        'country': '66c7a6c9e4bda21f4ab10f1b',
        'lang': 'fr'
    }
)
data = response.json()

PHP

<?php
$apiKey = 'votre-cle-api';
$countryId = '66c7a6c9e4bda21f4ab10f1b';
$url = "https://api.countrydataapi.com/v1/select/states?apikey={$apiKey}&country={$countryId}&lang=fr";

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

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

Angular

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

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

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

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

  constructor(private http: HttpClient) {}

  getStatesByCountry(countryId: string, lang: string = 'fr'): Observable<State[]> {
    const params = new HttpParams()
      .set('apikey', this.API_KEY)
      .set('country', countryId)
      .set('lang', lang);

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

// state-select.component.ts
import { Component, Input, Output, EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
import { CommonModule } from '@angular/common';
import { FormsModule } from '@angular/forms';
import { StateService } from './state.service';

@Component({
  selector: 'app-state-select',
  standalone: true,
  imports: [CommonModule, FormsModule],
  template: `
    <div *ngIf="loading">Chargement des régions...</div>
    <div *ngIf="error" class="error">{{ error }}</div>
    <select
      *ngIf="!loading && !error"
      [(ngModel)]="selectedState"
      (ngModelChange)="onStateChange($event)"
      [disabled]="!countryId"
    >
      <option value="">Sélectionnez une région...</option>
      <option *ngFor="let state of states" [value]="state.id">
        {{ state.name }}
      </option>
    </select>
  `
})
export class StateSelectComponent implements OnChanges {
  @Input() countryId: string = '';
  @Output() stateChange = new EventEmitter<string>();

  states: any[] = [];
  selectedState = '';
  loading = false;
  error: string | null = null;

  constructor(private stateService: StateService) {}

  ngOnChanges(changes: SimpleChanges) {
    if (changes['countryId'] && this.countryId) {
      this.loadStates();
    } else {
      this.states = [];
      this.selectedState = '';
    }
  }

  loadStates() {
    this.loading = true;
    this.error = null;

    this.stateService.getStatesByCountry(this.countryId, 'fr').subscribe({
      next: (data) => {
        this.states = data;
        this.loading = false;
      },
      error: (err) => {
        this.error = 'Échec du chargement des régions';
        this.loading = false;
      }
    });
  }

  onStateChange(stateId: string) {
    this.stateChange.emit(stateId);
  }
}

Format de Réponse

Réponse de Succès (France)

{
  "success": true,
  "data": [
    {
      "id": "66c7a6cae4bda21f4ab11d16",
      "name": "Auvergne-Rhône-Alpes"
    },
    {
      "id": "66c7a6cae4bda21f4ab11d17",
      "name": "Bourgogne-Franche-Comté"
    },
    {
      "id": "66c7a6cae4bda21f4ab11d18",
      "name": "Bretagne"
    },
    {
      "id": "66c7a6cae4bda21f4ab11d19",
      "name": "Centre-Val de Loire"
    },
    {
      "id": "66c7a6cae4bda21f4ab11d1a",
      "name": "Corse"
    }
    // ... 18 régions au total
  ]
}

Champs de Réponse

Champ	Type	Description
`success`	boolean	Indique si la requête a réussi
`data`	array	Tableau d'objets région/province
`data[].id`	string	Identifiant unique de la région (MongoDB ObjectId)
`data[].name`	string	Nom de la région/province dans la langue demandée

Réponse d'Erreur

{
  "success": false,
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Le paramètre requis 'country' est manquant"
  }
}

Résultat Vide

Si un pays n'a pas de régions (ex : petits pays) :

{
  "success": true,
  "data": []
}

Utilisation des Tokens

Cet endpoint consomme 1 token par requête.

Astuce : Mettez les données de régions en cache par ID de pays pour réduire les appels API lorsque les utilisateurs naviguent d'avant en arrière.

Exemple de Dropdown en Cascade

HTML

<select id="country" onchange="chargerRegions(this.value)">
  <option value="">Sélectionnez un pays...</option>
  <!-- Rempli depuis /select/countries -->
</select>

<select id="state" disabled>
  <option value="">Sélectionnez une région...</option>
</select>

<script>
const API_KEY = 'votre-cle-api';

async function chargerRegions(countryId) {
  const stateSelect = document.getElementById('state');

  // Réinitialiser et désactiver
  stateSelect.innerHTML = '<option value="">Chargement...</option>';
  stateSelect.disabled = true;

  if (!countryId) {
    stateSelect.innerHTML = '<option value="">Sélectionnez une région...</option>';
    return;
  }

  try {
    const response = await fetch(
      `https://api.countrydataapi.com/v1/select/states?apikey=${API_KEY}&country=${countryId}&lang=fr`
    );
    const { success, data, error } = await response.json();

    if (!success) {
      console.error('Erreur API:', error);
      stateSelect.innerHTML = '<option value="">Erreur de chargement des régions</option>';
      return;
    }

    stateSelect.innerHTML = '<option value="">Sélectionnez une région...</option>';
    data.forEach(state => {
      stateSelect.add(new Option(state.name, state.id));
    });
    stateSelect.disabled = false;
  } catch (err) {
    console.error('Erreur Réseau:', err);
    stateSelect.innerHTML = '<option value="">Erreur de chargement des régions</option>';
  }
}
</script>

Composant React

import { useState, useEffect } from 'react';

function StateSelect({ countryId, onChange }) {
  const [states, setStates] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (!countryId) {
      setStates([]);
      return;
    }

    setLoading(true);
    fetch(
      `https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=${countryId}&lang=fr`
    )
      .then(res => res.json())
      .then(({ data }) => {
        setStates(data || []);
        setLoading(false);
      })
      .catch(err => {
        console.error(err);
        setLoading(false);
      });
  }, [countryId]);

  return (
    <select onChange={e => onChange(e.target.value)} disabled={!countryId || loading}>
      <option value="">
        {loading ? 'Chargement...' : 'Sélectionnez une région...'}
      </option>
      {states.map(state => (
        <option key={state.id} value={state.id}>
          {state.name}
        </option>
      ))}
    </select>
  );
}

Composant Vue

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

const props = defineProps(['countryId']);
const emit = defineEmits(['change']);

const states = ref([]);
const loading = ref(false);

watch(() => props.countryId, async (countryId) => {
  if (!countryId) {
    states.value = [];
    return;
  }

  loading.value = true;
  try {
    const response = await fetch(
      `https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=${countryId}&lang=fr`
    );
    const { data } = await response.json();
    states.value = data || [];
  } catch (err) {
    console.error(err);
  } finally {
    loading.value = false;
  }
});
</script>

<template>
  <select @change="emit('change', $event.target.value)" :disabled="!countryId || loading">
    <option value="">{{ loading ? 'Chargement...' : 'Sélectionnez une région...' }}</option>
    <option v-for="state in states" :key="state.id" :value="state.id">
      {{ state.name }}
    </option>
  </select>
</template>

Exemples par Pays

France (18 régions)

const FRANCE_ID = '66c7a6c9e4bda21f4ab10f1b';
const response = await fetch(
  `https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=${FRANCE_ID}&lang=fr`
);
// Retourne : Auvergne-Rhône-Alpes, Bretagne, ... Occitanie

Canada (10 provinces + 3 territoires)

const CANADA_ID = '66c7a6c9e4bda21f4ab10ef7';
const response = await fetch(
  `https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=${CANADA_ID}&lang=fr`
);
// Retourne : Alberta, Colombie-Britannique, ... Yukon

Belgique (10 provinces)

const BELGIUM_ID = '66c7a6c9e4bda21f4ab10ee9';
const response = await fetch(
  `https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=${BELGIUM_ID}&lang=fr`
);
// Retourne : Anvers, Brabant flamand, ... Luxembourg

Stratégie de Cache

Mettez les régions en cache par pays pour minimiser les appels API :

const stateCache = new Map();

async function getRegions(countryId) {
  // Vérifier le cache d'abord
  if (stateCache.has(countryId)) {
    return stateCache.get(countryId);
  }

  // Récupérer depuis l'API
  const response = await fetch(
    `https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=${countryId}&lang=fr`
  );
  const { data } = await response.json();

  // Sauvegarder en cache
  stateCache.set(countryId, data);

  return data;
}

Gestion des Erreurs

Gérez toujours les erreurs avec élégance :

async function chargerRegions(countryId) {
  try {
    const response = await fetch(
      `https://api.countrydataapi.com/v1/select/states?apikey=votre-cle-api&country=${countryId}`
    );

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

    const result = await response.json();

    if (!result.success) {
      throw new Error(result.error?.message || 'Erreur API');
    }

    return result.data;
  } catch (err) {
    console.error('Échec du chargement des régions:', err);
    // Afficher un message convivial à l'utilisateur
    alert('Échec du chargement des régions. Veuillez réessayer.');
    return [];
  }
}

Conseils de Performance

Chargement lazy : Ne récupérer que lorsqu'un pays est sélectionné
Cache par pays : Stocker en mémoire ou localStorage
Debounce sur les requêtes : Si vous utilisez recherche/filtre
Afficher l'état de chargement : Fournir un feedback visuel

Limites de Taux

Forfait gratuit : 100 requêtes/jour
Forfait Basic : 1 000 requêtes/jour
Forfait Pro : 10 000 requêtes/jour
Forfait Enterprise : Illimité

Consultez notre page de tarifs pour plus de details.

Erreurs Courantes

Code d'Erreur	Description	Solution
`INVALID_API_KEY`	Clé API invalide	Vérifiez votre clé API dans le tableau de bord du compte
`MISSING_PARAMETER`	Paramètre `country` manquant	Incluez l'ID du pays dans la requête
`INVALID_COUNTRY_ID`	Format de l'ID du pays invalide	Utilisez un MongoDB ObjectId valide depuis `/select/countries`
`QUOTA_EXCEEDED`	Limite quotidienne de tokens atteinte	Mettez à niveau le forfait ou attendez la réinitialisation

Consultez la documentation des Codes d'Erreur pour toutes les erreurs possibles.

Endpoints Associés

GET /v1/select/countries - Obtenir tous les pays
GET /v1/select/cities - Obtenir les villes par région
GET /v1/states/all - Obtenir les données complètes des régions

Guides d'Intégration Complets

Formulaire d'Adresse avec Selects en Cascade - Tutoriel complet
Intégration React - Hooks personnalisés
Intégration Vue - Composables

Besoin d'Aide ?

Consultez notre documentation des Codes d'Erreur
Voir le guide d'Authentification
Contactez le support via le tableau de bord de votre compte

Note : Certains pays n'ont pas de divisions administratives (ex : Monaco, Cité du Vatican) et retourneront un tableau vide. Gérez toujours les résultats vides avec élégance dans votre interface.

Sélectionner des Régions