{"openapi":"3.1.0","info":{"title":"CAPIT Cities API","version":"1.0.0","description":"Public : sélection mondiale fixe de 5 000 villes. Abonnés éligibles : toute la base. Clé secrète exclusivement côté serveur ; navigateur : jeton temporaire lié à une origine et soumis aux quotas du compte. Données GeoNames (CC BY), OpenStreetMap (ODbL), Wikidata (CC0) et sources documentées. Des valeurs historiques restent non vérifiées. Les accès techniques payants ne suppriment pas les droits des licences ouvertes."},"servers":[{"url":"https://api.capit.net"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"ack_… serveur ; act_… widget (5 minutes)"}},"schemas":{"City":{"type":"object","properties":{"source_id":{"type":["string","null"],"description":"Alias de id : identifiant de la même ville."},"name":{"type":["string","null"],"description":"Nom dans la langue demandée par lang ; repli français si cette variante manque."},"historical_name":{"type":["string","null"],"description":"Nom original conservé dans la colonne source « nom historique » ; il ne désigne pas nécessairement un ancien toponyme."},"local_names":{"type":["object","array","string","null"],"description":"Variantes locales documentées, au format JSON."},"english_name":{"type":["string","null"],"description":"Nom anglais documenté."},"population":{"type":["number","null"],"description":"Nombre d'habitants documenté (cellule vide si inconnu, jamais 0 par défaut). Source : INSEE (populations municipales 2023), Wikidata (P1082) ou GeoNames selon [population_source]."},"longitude":{"type":["number","null"],"description":"Longitude GPS en degrés décimaux (WGS84), précision maximale locale conservée. Source : OpenStreetMap (ODbL) et rapprochement GeoNames compatible."},"latitude":{"type":["number","null"],"description":"Latitude GPS en degrés décimaux (WGS84), précision maximale locale conservée. Source : OpenStreetMap (ODbL) et rapprochement GeoNames compatible."},"coordinate_match_distance_km":{"type":["number","null"],"description":"Distance en kilomètres entre la coordonnée source et le lieu GeoNames rapproché. Source : Calcul géodésique (formule de Haversine) lors du rapprochement."},"coordinate_match_status":{"type":["string","null"],"description":"Statut de confiance du rapprochement par coordonnées (name_agrees, coordinates_unique, coordinates_guess, geonames_direct). Source : Pipeline de contrôle géographique AffectionPlus."},"postcode":{"type":["string","null"],"description":"Un ou plusieurs codes postaux séparés par point-virgule (;), zéros initiaux préservés. Source : API Géo / La Poste (France), GeoNames Postal Codes, Wikidata ou fichier initial."},"name_local_phonetic":{"type":["string","null"],"description":"Aide de lecture en alphabet latin pour les noms en écritures non latines. Source : Variantes latines GeoNames et nom anglais de repli."},"alternate_names":{"type":["object","array","string","null"],"description":"Liste JSON des variantes orthographiques, exonymes et translittérations connus. Source : GeoNames alternateNamesV2 et données initiales."},"country_code":{"type":["string","null"],"description":"Code pays ou territoire ISO 3166-1 alpha-2 (ex. FR, GB, DK, GL). Source : GeoNames et contexte national vérifié."},"admin1":{"type":["string","null"],"description":"Nom de la division administrative de 1er niveau (région, État, Land, province). Source : GeoNames admin1CodesASCII et API Géo / INSEE (France)."},"admin1_en":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en anglais."},"admin1_fr":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en français."},"admin2":{"type":["string","null"],"description":"Nom de la division administrative de 2e niveau (département, comté, district). Source : GeoNames admin2Codes et API Géo / INSEE (France)."},"admin2_en":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en anglais."},"admin2_fr":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en français."},"admin1_code":{"type":["string","null"],"description":"Code administratif composite de niveau 1 (GeoNames ou préfixe INSEE:). Source : GeoNames / INSEE."},"admin2_code":{"type":["string","null"],"description":"Code administratif composite de niveau 2 (GeoNames ou préfixe INSEE:). Source : GeoNames / INSEE."},"municipality_code":{"type":["string","null"],"description":"Code officiel de la commune (notamment code INSEE en France). Source : API Géo / INSEE."},"timezone":{"type":["string","null"],"description":"Identifiant du fuseau horaire IANA (ex. Europe/Paris, America/New_York). Source : GeoNames."},"feature_code":{"type":["string","null"],"description":"Code de classification GeoNames du lieu habité (PPLC, PPLA, PPLA2, PPL…). Source : GeoNames."},"administrative_role":{"type":["string","null"],"description":"Rôle administratif normalisé (national_capital, admin1_seat, admin2_seat…). Source : Déduit du feature_code GeoNames."},"administrative_role_en":{"type":["string","null"],"description":"Libellé du rôle administratif en anglais."},"administrative_role_fr":{"type":["string","null"],"description":"Libellé du rôle administratif en français."},"elevation_m":{"type":["number","null"],"description":"Altitude en mètres (uniquement lorsqu'une mesure explicite est fournie). Source : GeoNames."},"population_year":{"type":["string","null"],"description":"Année de référence du recensement ou de l'estimation de population. Source : INSEE (2023) ou qualificatif point in time (P585) de Wikidata."},"population_source":{"type":["string","null"],"description":"Source exacte du chiffre de population (insee-2023, wd:<QID>, gn:<id>, original_unverified). Source : Traçabilité du pipeline d'enrichissement."},"population_scope":{"type":["string","null"],"description":"Périmètre géographique de la population (commune, wikidata_entity, geonames_place). Source : Traçabilité du pipeline d'enrichissement."},"languages_official":{"type":["object","array","string","null"],"description":"Liste JSON des codes de langues officielles applicables. Source : Wikidata (P37) et GeoNames countryInfo.txt."},"languages_spoken":{"type":["object","array","string","null"],"description":"Liste JSON des langues parlées ou utilisées documentées. Source : Wikidata (P2936) et GeoNames countryInfo.txt."},"languages_scope":{"type":["object","array","string","null"],"description":"Objet JSON précisant si les langues relèvent de la ville (city) ou du pays (country). Source : Métadonnée de portée linguistique."},"languages_source":{"type":["object","array","string","null"],"description":"Objet JSON indiquant la source des langues officielles et parlées. Source : Wikidata et GeoNames countryInfo."},"languages_year":{"type":["string","null"],"description":"Année de référence des données linguistiques lorsque datée. Source : Wikidata."},"area_km2":{"type":["number","null"],"description":"Superficie en kilomètres carrés (km²). Source : API Géo / INSEE (hectares convertis en km²) et Wikidata (P2046)."},"area_scope":{"type":["string","null"],"description":"Entité exacte couverte par la superficie (commune:<INSEE> ou wikidata_entity:<QID>). Source : API Géo / Wikidata."},"area_source":{"type":["string","null"],"description":"Référentiel ayant fourni la superficie (geo-fr:<INSEE> ou wd:<QID>). Source : API Géo / Wikidata."},"density_km2":{"type":["number","null"],"description":"Densité d'habitants par km² (calculée uniquement si population datée et superficie ont le même périmètre). Source : Calcul vérifié sur [population] / [area_km2]."},"demonym_en":{"type":["string","null"],"description":"Gentilé attesté en anglais."},"demonym_fr":{"type":["string","null"],"description":"Gentilé attesté en français. Source : Wikidata P1549."},"demonyms_local":{"type":["object","array","string","null"],"description":"Objet JSON de toutes les formes de gentilés attestées par code de langue. Source : Wikidata (P1549)."},"demonym_source":{"type":["string","null"],"description":"Identifiant de l'entité Wikidata source du gentilé. Source : Wikidata."},"demonym_scope":{"type":["string","null"],"description":"Périmètre d'application du gentilé (ville ou commune). Source : Wikidata / INSEE."},"geonames_id":{"type":["string","null"],"description":"Identifiant numérique GeoNames du lieu. Source : GeoNames."},"wikidata_id":{"type":["string","null"],"description":"Identifiant d'entité Wikidata (ex. Q90 pour Paris). Source : Wikidata (via propriété P1566 GeoNames ID ou P374 INSEE)."},"official_website":{"type":["string","null"],"description":"Site web officiel de la municipalité ou localité. Source : Wikidata (P856)."},"wikipedia_url":{"type":["string","null"],"description":"Lien Wikipédia conservé de la source retenue. La langue du lien est indiquée par wikipedia_language ; ce lien ne change pas avec le paramètre lang."},"postcode_source":{"type":["string","null"],"description":"Source des codes postaux (geo-fr, gn-postal, wd, original_unverified). Source : Traçabilité postale."},"postcode_status":{"type":["string","null"],"description":"Qualité de couverture postale (commune_codes, documented_not_exhaustive, partial_codes, original_unverified). Source : Diagnostic de couverture postale."},"data_sources":{"type":["string","null"],"description":"Liste séparée par ';' de toutes les sources mobilisées pour construire la ligne. Source : Journal de provenance par ligne (osm, gn, wd, insee-2023, geo-fr, cldr, un-m49, iso-3166-2)."},"updated_at":{"type":["string","null"],"description":"Date du dernier traitement d'enrichissement ou de vérification de la ligne (AAAA-MM-JJ). Source : Pipeline AffectionPlus."},"enrichment_status":{"type":["string","null"],"description":"Résultat global du rapprochement (name_coordinates, unmatched, coordinates_guess, geonames_direct…). Source : Pipeline AffectionPlus."},"country_name":{"type":["string","null"],"description":"Nom du pays dans la langue demandée par lang ; repli français. Source : CLDR / Babel."},"admin1_geonames_id":{"type":["string","null"],"description":"Identifiant GeoNames propre à la région / division de 1er niveau. Source : GeoNames admin1CodesASCII."},"admin2_geonames_id":{"type":["string","null"],"description":"Identifiant GeoNames propre au département / division de 2e niveau. Source : GeoNames admin2Codes."},"wikipedia_language":{"type":["string","null"],"description":"Code de langue de l'URL Wikipédia fournie (ex. fr, en, de). Source : Extrait du sous-domaine de [wikipedia_url]."},"country_code_iso3":{"type":["string","null"],"description":"Code pays normalisé ISO 3166-1 alpha-3 à trois lettres (ex. FRA, GBR, DNK). Source : GeoNames countryInfo.txt."},"continent_code":{"type":["string","null"],"description":"Code du continent à deux lettres (EU, AS, AF, NA, SA, OC, AN). Source : GeoNames countryInfo.txt."},"continent":{"type":["string","null"],"description":"Nom du continent dans la langue demandée par lang ; repli français. Source : ONU M49 / CLDR."},"name_ascii":{"type":["string","null"],"description":"Nom de la ville en caractères ASCII purs (sans accents), idéal pour l'indexation et la recherche. Source : GeoNames asciiname."},"duplicate_name_in_country":{"type":["boolean","null"],"description":"Booléen (true / false) signalant si plusieurs villes du même pays portent le même nom ASCII. Source : Calcul sur l'ensemble des identifiants GeoNames du pays."},"coordinate_source":{"type":["string","null"],"description":"Source des coordonnées GPS : OpenStreetMap lorsque longitude et latitude sont renseignées. Source : OpenStreetMap (sous licence ODbL)."},"subregion_code_m49":{"type":["string","null"],"description":"Code numérique officiel M49 des Nations Unies pour la sous-région géographique (ex. 155, 039). Source : Nations Unies — Classification statistique M49."},"subregion_m49":{"type":["string","null"],"description":"Nom de la sous-région ONU M49 dans la langue demandée par lang ; repli français."},"admin1_iso_code":{"type":["string","null"],"description":"Code officiel ISO 3166-2 de la région ou de l'État fédéré (ex. FR-ARA, US-CA, DE-BY). Source : Wikidata (propriété P300 associée au GeoNames ID de la région)."},"importance_tier":{"type":["number","null"],"description":"Indice hiérarchique de 1 à 5 (1 = capitale nationale ou ≥ 1 M hab. ; 2 = capitale régionale ou ≥ 200 k ; 3 = chef-lieu ou ≥ 50 k ; 4 = ≥ 10 k ; 5 = localité). Source : Calcul algorithmique sur [administrative_role], [feature_code] et [population]."},"currency_code":{"type":["string","null"],"description":"Code devise officiel ISO 4217 du pays ou territoire (ex. EUR, USD, GBP, DKK). Source : GeoNames countryInfo.txt."},"phone_prefix":{"type":["string","null"],"description":"Indicatif téléphonique international du pays ou territoire (ex. +33, +44, +1). Source : GeoNames countryInfo.txt."},"postal_code_format":{"type":["string","null"],"description":"Format / masque officiel des codes postaux du pays (ex. ##### en France). Source : GeoNames countryInfo.txt."},"country_tld":{"type":["string","null"],"description":"Domaine Internet national de premier niveau ccTLD (ex. .fr, .uk, .dk). Source : GeoNames countryInfo.txt."},"population_proper":{"type":["number","null"],"description":"Population municipale stricte (dans les limites administratives de la commune / localité). Source : INSEE (populations municipales 2023), Wikidata (P1082 municipal) ou GeoNames."},"population_urban":{"type":["number","null"],"description":"Population de l'agglomération / aire urbaine / métropole rattachée à la ville. Source : Wikidata (aires urbaines et métropolitaines P1082) et calcul d'agglomération spatiale GeoNames (hors sous-quartiers PPLX)."},"population_urban_source":{"type":["string","null"],"description":"Source de la population urbaine (wd:<QID>, gn_agglomeration ou proper_only). Source : Traçabilité de l'agglomération urbaine AffectionPlus."},"admin1_de":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en allemand."},"admin2_de":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en allemand."},"administrative_role_de":{"type":["string","null"],"description":"Libellé du rôle administratif en allemand."},"demonym_de":{"type":["string","null"],"description":"Gentilé attesté en allemand."},"admin1_es":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en espagnol."},"admin2_es":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en espagnol."},"administrative_role_es":{"type":["string","null"],"description":"Libellé du rôle administratif en espagnol."},"demonym_es":{"type":["string","null"],"description":"Gentilé attesté en espagnol."},"admin1_it":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en italien."},"admin2_it":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en italien."},"administrative_role_it":{"type":["string","null"],"description":"Libellé du rôle administratif en italien."},"demonym_it":{"type":["string","null"],"description":"Gentilé attesté en italien."},"admin1_pt":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en portugais."},"admin2_pt":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en portugais."},"administrative_role_pt":{"type":["string","null"],"description":"Libellé du rôle administratif en portugais."},"demonym_pt":{"type":["string","null"],"description":"Gentilé attesté en portugais."},"admin1_nl":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en néerlandais."},"admin2_nl":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en néerlandais."},"administrative_role_nl":{"type":["string","null"],"description":"Libellé du rôle administratif en néerlandais."},"demonym_nl":{"type":["string","null"],"description":"Gentilé attesté en néerlandais."},"admin1_pl":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en polonais."},"admin2_pl":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en polonais."},"administrative_role_pl":{"type":["string","null"],"description":"Libellé du rôle administratif en polonais."},"demonym_pl":{"type":["string","null"],"description":"Gentilé attesté en polonais."},"admin1_tr":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau en turc."},"admin2_tr":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau en turc."},"administrative_role_tr":{"type":["string","null"],"description":"Libellé du rôle administratif en turc."},"demonym_tr":{"type":["string","null"],"description":"Gentilé attesté en turc."},"id":{"type":["string","null"],"description":"Identifiant unique et stable de la ville, conservé en texte, indépendant du pays."},"country":{"type":["string","null"],"description":"Alias de country_code : code ISO 3166-1 alpha-2 du pays ou territoire."},"region":{"type":["string","null"],"description":"Nom de la division administrative de premier niveau dans la langue demandée ; repli sur admin1."},"department":{"type":["string","null"],"description":"Nom de la division administrative de deuxième niveau dans la langue demandée ; repli sur admin2."},"name_language":{"type":["string","null"],"description":"Langue attestée du nom retourné ; fr lorsque la variante demandée manque."}}}}},"paths":{"/v1/cities":{"get":{"summary":"Consulter les villes","security":[{},{"bearer":[]}],"parameters":[{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO alpha-2 ; filtre appliqué APRÈS la sélection mondiale des 5 000 villes pour le niveau public."},{"name":"fields","in":"query","schema":{"type":"string"},"example":"name,country,region,population"},{"name":"sort","in":"query","schema":{"type":"string","default":"-population"},"description":"1 à 4 propriétés, préfixe - pour ordre décroissant ; identifiant ajouté pour stabiliser le tri."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":2000000,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.nextCursor, même filtre et tri -population ; exclusif avec page."},{"name":"lang","in":"query","schema":{"type":"string","enum":["fr","en","de","es","it","pt","nl","pl","tr"],"default":"fr"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Sous-chaîne littérale dans les noms attestés des neuf langues, le nom anglais et le nom ASCII ; pas de normalisation phonétique. Un jeton limité à certains champs recherche seulement ses champs autorisés."},{"name":"bbox","in":"query","schema":{"type":"string"},"description":"ouest,sud,est,nord ; ouest > est traverse l’antiméridien."},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"filter[population][gte]=100000 ; propriétés/opérateurs dans /v1/cities/schema ; in et between utilisent une virgule. isnull=true|false. Comparaisons avec NULL exclues sauf isnull. Au plus 20 filtres."}],"responses":{"200":{"description":"Résultats, pagination, millésime et quota","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/City"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"},"nextCursor":{"type":["string","null"]},"version":{"type":"string"},"limits":{"type":"object"}}}}}}}},"400":{"description":"Paramètre invalide"},"401":{"description":"Clé invalide"},"403":{"description":"Droit insuffisant"},"429":{"description":"Quota dépassé : Retry-After"},"503":{"description":"Base indisponible ou requête trop coûteuse"}}}},"/v1/cities/schema":{"get":{"summary":"Découvrir toutes les propriétés","responses":{"200":{"description":"Schéma, types, opérateurs, langues et disponibilité"}}}},"/v1/cities/export":{"get":{"summary":"Télécharger un lot JSON (jusqu’à 1 000 lignes), puis nextCursor","security":[{"bearer":[]}],"parameters":[{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO alpha-2 ; filtre appliqué APRÈS la sélection mondiale des 5 000 villes pour le niveau public."},{"name":"fields","in":"query","schema":{"type":"string"},"example":"name,country,region,population"},{"name":"sort","in":"query","schema":{"type":"string","default":"-population"},"description":"1 à 4 propriétés, préfixe - pour ordre décroissant ; identifiant ajouté pour stabiliser le tri."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":2000000,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":10}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.nextCursor, même filtre et tri -population ; exclusif avec page."},{"name":"lang","in":"query","schema":{"type":"string","enum":["fr","en","de","es","it","pt","nl","pl","tr"],"default":"fr"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Sous-chaîne littérale dans les noms attestés des neuf langues, le nom anglais et le nom ASCII ; pas de normalisation phonétique. Un jeton limité à certains champs recherche seulement ses champs autorisés."},{"name":"bbox","in":"query","schema":{"type":"string"},"description":"ouest,sud,est,nord ; ouest > est traverse l’antiméridien."},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"filter[population][gte]=100000 ; propriétés/opérateurs dans /v1/cities/schema ; in et between utilisent une virgule. isnull=true|false. Comparaisons avec NULL exclues sauf isnull. Au plus 20 filtres."}],"responses":{"200":{"description":"Résultats, pagination, millésime et quota","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/City"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"},"nextCursor":{"type":["string","null"]},"version":{"type":"string"},"limits":{"type":"object"}}}}}}}},"400":{"description":"Paramètre invalide"},"401":{"description":"Clé invalide"},"403":{"description":"Droit insuffisant"},"429":{"description":"Quota dépassé : Retry-After"},"503":{"description":"Base indisponible ou requête trop coûteuse"}}}},"/v1/widget-token":{"post":{"summary":"Émettre un jeton de widget depuis le serveur du webmaster","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["origin"],"properties":{"origin":{"type":"string","format":"uri"},"country":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"token, expiresIn (300 s), origin"},"400":{"description":"Paramètre invalide"},"401":{"description":"Clé invalide"},"403":{"description":"Droit insuffisant"},"429":{"description":"Quota dépassé : Retry-After"},"503":{"description":"Base indisponible ou requête trop coûteuse"}}}}}}