> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de géolocalisation IP

> L'API de géolocalisation IP Cleariflow est une API JSON RESTful rapide, efficace et moderne qui identifie la localisation et les détails supplémentaires des adresses IP dans plus de 190 pays.

L'API fonctionne avec une simplicité remarquable : il suffit de fournir votre clé API ainsi qu'une adresse IP, et vous recevrez des données de localisation complètes incluant les codes postaux, les noms de villes, les informations régionales, les détails du pays et des coordonnées latitude/longitude précises.

## Premiers pas

### Architecture REST

Comme toutes les API Cleariflow, l'API de géolocalisation IP suit les principes REST. Elle utilise des URL prévisibles, orientées ressources, et des codes de statut HTTP pour indiquer les erreurs.

### Sécurité HTTPS

Toutes les communications avec l'API de géolocalisation IP doivent être sécurisées par des protocoles TLS 1.2 ou supérieur.

### Versionnage de l'API

Toutes les API Cleariflow intègrent le versionnage. L'API de géolocalisation IP fonctionne actuellement en version 1.

### Authentification par clé API

Votre clé API sert d'identifiant d'authentification unique pour accéder à l'API de géolocalisation IP Cleariflow. Il est important de noter que chaque API Cleariflow nécessite une clé API distincte ; vous aurez donc besoin de clés séparées pour différents services comme l'API de géolocalisation IP et l'API de validation d'e-mail. Pour authentifier vos requêtes, ajoutez votre clé API à l'URL de base.

### URL de base

```
https://ipgeolocation.cleariflow.com/v1/
```

### Endpoint de géolocalisation

L'API de géolocalisation IP Cleariflow ne requiert que votre clé API unique et détecte automatiquement l'adresse IP du client demandeur. Vous pouvez également inclure le paramètre « ip\_address » pour spécifier une IP particulière à analyser :

```
https://ipgeolocation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 94.198.41.118 (optional)
```

Il s'agit d'une requête réussie, renvoyant l'adresse IP et les détails associés ci-dessous :

<ResponseExample>
  ```json theme={"system"}
  {
      "ip_address": "80.255.13.30",
      "city": null,
      "city_geoname_id": null,
      "region": null,
      "region_iso_code": null,
      "region_geoname_id": null,
      "postal_code": null,
      "country": "Germany",
      "country_code": "DE",
      "country_geoname_id": 2921044,
      "country_is_eu": true,
      "continent": "Europe",
      "continent_code": "EU",
      "continent_geoname_id": 6255148,
      "longitude": 9.491,
      "latitude": 51.2993,
      "security": {
          "is_vpn": true,
          "is_proxy": false,
          "vpn_provider": "NordVPN"
      },
      "timezone": {
          "name": "Europe/Berlin",
          "abbreviation": "CEST",
          "gmt_offset": 2,
          "current_time": "21:21:22",
          "is_dst": true
      },
      "flag": {
          "emoji": "🇩🇪",
          "unicode": "U+1F1E9 U+1F1EA",
          "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
          "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
      },
      "currency": {
          "currency_name": "Euros",
          "currency_code": "EUR"
      },
      "connection": {
          "autonomous_system_number": 201011,
          "autonomous_system_organization": "Core-Backbone GmbH",
          "connection_type": null,
          "isp_name": null,
          "organization_name": null
      }
  }
  ```
</ResponseExample>

### Paramètres de requête

<ParamField query="api_key" type="String" required>
  Votre clé API unique. Notez que chaque utilisateur possède des clés API uniques pour chaque API Cleariflow ; votre clé de l'API de géolocalisation IP ne fonctionnera pas pour votre API de validation d'e-mail, par exemple.
</ParamField>

<ParamField query="ip_address" type="String">
  L'adresse IP à géolocaliser. Les adresses IPv4 et IPv6 sont prises en charge. Notez que si vous laissez ce paramètre vide, le service géolocalisera l'adresse IP à partir de laquelle la requête a été effectuée.
</ParamField>

<ParamField query="fields" type="String">
  Liste séparée par des virgules de clés **de premier niveau** à renvoyer (par exemple, `?fields=country,security`). Pour inclure les indicateurs VPN/proxy, utilisez `security` — l'objet entier est renvoyé (`is_vpn`, `is_proxy` et `vpn_provider` le cas échéant). Les clés imbriquées telles que `is_vpn` seules ne sont pas prises en charge.
</ParamField>

### Paramètres de réponse

La réponse de l'API est renvoyée dans un [format JSON](https://www.json.org/json-en.html) universel et léger.

<ResponseField name="ip_address" type="String">
  L'adresse IP soumise pour géolocalisation.
</ResponseField>

<ResponseField name="city" type="String">
  Nom de la ville.
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  ID geoname de la ville.
</ResponseField>

<ResponseField name="region" type="String">
  État ou province dans lequel la ville est située.
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  Code ISO 3166-2 de l'État ou de la province.
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  ID geoname de l'État ou de la province.
</ResponseField>

<ResponseField name="postal_code" type="String">
  Code postal.
</ResponseField>

<ResponseField name="country" type="String">
  Nom du pays.
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  Code ISO 3166-1 alpha-2 du pays.
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  ID geoname du pays.
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  Vrai si le pays est dans l'UE, faux sinon.
</ResponseField>

<ResponseField name="continent" type="String">
  Nom du continent.
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  Code continent à 2 lettres : AF, AS, EU, NA, OC, SA, AN.
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  ID geoname du continent.
</ResponseField>

<ResponseField name="longitude" type="Float">
  Valeur décimale de la longitude.
</ResponseField>

<ResponseField name="latitude" type="Float">
  Valeur décimale de la latitude.
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  `true` lorsque l'IP correspond à la base de données des nœuds de sortie VPN (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  `true` lorsque l'IP correspond à la base de données proxy (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  Nom du service VPN depuis la MMDB (par exemple, `NordVPN`). Omis lorsque `is_vpn` est `false`.
</ResponseField>

<ResponseField name="timezone.name" type="String">
  Nom du fuseau horaire depuis la base de données IANA Time Zone.
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  Abréviation du fuseau horaire, également depuis la base de données IANA Time Zone.
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  Décalage du fuseau horaire par rapport au temps moyen de Greenwich (GMT).
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  Heure actuelle dans le fuseau horaire local.
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  Vrai si la localisation est actuellement en heure d'été (DST).
</ResponseField>

<ResponseField name="flag.svg" type="String">
  Lien vers une version hébergée du drapeau du pays au format SVG.
</ResponseField>

<ResponseField name="flag.png" type="String">
  Lien vers une version hébergée du drapeau du pays au format PNG.
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  Drapeau du pays sous forme d'emoji.
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Drapeau du pays en unicode.
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  Nom de la devise.
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  Code de la devise au format ISO 4217.
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  Déduit du nom de l'organisation ASN (par exemple, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN et proxy sont signalés dans `security`, pas ici.
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  Numéro de système autonome.
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  Nom de l'organisation du système autonome.
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  Nom du fournisseur d'accès Internet (FAI).
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  Nom de l'organisation.
</ResponseField>

### Limiter les champs de réponse

Vous pouvez choisir de ne recevoir que quelques champs de la réponse JSON. Pour ce faire, incluez une valeur fields dans les paramètres de requête avec une liste séparée par des virgules des clés de premier niveau que vous souhaitez recevoir.

Par exemple, une requête pour obtenir uniquement le pays et la ville d'une IP ressemblera à ceci :

```
https://ipgeolocation.cleariflow.com/v1/
    ? api_key = YOUR_API_KEY
    & ip_address = 94.198.41.122
    & fields = country,city
```

La réponse ressemblerait à ceci :

```json theme={"system"}
{
    "city": "Vienna",
    "country": "Austria"
}
```

## Cas d'utilisation

### Géolocaliser un visiteur de site web

Pour demander la géolocalisation à partir d'une adresse IP, incluez simplement votre clé API unique dans le modèle ci-dessous.

Notez que vous n'avez pas besoin de connaître l'IP du visiteur pour effectuer la requête.

```javascript theme={"system"}
$.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
   console.log(data.ip_address);
   console.log(data.country);
})
```

C'est tout ce dont vous avez besoin pour obtenir la géolocalisation et d'autres données d'un visiteur ! Il n'y a qu'un seul paramètre requis : votre clé API unique.

## Codes de réponse et d'erreur

Lorsqu'une requête échoue pour une raison quelconque, une erreur est également renvoyée au format JSON. Les erreurs comprennent un code d'erreur et une description, que vous trouverez en détail ci-dessous.

| Code | Type                  | Détails                                                                                                                                                          |
| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Tout a fonctionné comme prévu.                                                                                                                                   |
| 204  | OK                    | Il n'y a pas de données de localisation pour l'IP soumise.                                                                                                       |
| 400  | Bad request           | Mauvaise requête.                                                                                                                                                |
| 401  | Unauthorized          | La requête était inacceptable. Généralement due à une clé API manquante ou incorrecte.                                                                           |
| 422  | Quota reached         | La requête a été interrompue en raison de crédits API insuffisants. (Forfaits gratuits)                                                                          |
| 429  | Too many requests     | La requête a été interrompue car le nombre de requêtes autorisées par seconde a été atteint. Cela se produit sur les forfaits gratuits, limités à 1 par seconde. |
| 500  | Internal server error | La requête n'a pas pu être complétée en raison d'une erreur côté serveur.                                                                                        |
| 503  | Service unavailable   | Le serveur était indisponible.                                                                                                                                   |

## Codes pays

Voici une liste des codes pays ISO 3166 Alpha 2 à deux lettres utilisés dans la réponse. Consultez cette liste au format [CSV](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing).

| Nom du pays                      | Code pays |
| -------------------------------- | --------- |
| Afghanistan                      | AF        |
| Albanie                          | AL        |
| Algérie                          | DZ        |
| Samoa américaines                | AS        |
| Andorre                          | AD        |
| Angola                           | AO        |
| Anguilla                         | AI        |
| Antigua-et-Barbuda               | AG        |
| Argentine                        | AR        |
| Arménie                          | AM        |
| Aruba                            | AW        |
| Australie                        | AU        |
| Autriche                         | AT        |
| Azerbaïdjan                      | AZ        |
| Bahreïn                          | BH        |
| Bangladesh                       | BD        |
| Barbade                          | BB        |
| Biélorussie                      | BY        |
| Belgique                         | BE        |
| Belize                           | BZ        |
| Bénin                            | BJ        |
| Bermudes                         | BM        |
| Bhoutan                          | BT        |
| Bolivie                          | BO        |
| Bosnie-Herzégovine               | BA        |
| Botswana                         | BW        |
| Brésil                           | BR        |
| Îles Vierges britanniques        | VG        |
| Brunei                           | BN        |
| Bulgarie                         | BG        |
| Burkina Faso                     | BF        |
| Burundi                          | BI        |
| Cap-Vert                         | CV        |
| Cambodge                         | KH        |
| Cameroun                         | CM        |
| Canada                           | CA        |
| Îles Caïmans                     | KY        |
| République centrafricaine        | CF        |
| Tchad                            | TD        |
| Chili                            | CL        |
| Chine                            | CN        |
| Colombie                         | CO        |
| Comores                          | KM        |
| Congo                            | CG        |
| République démocratique du Congo | CD        |
| Îles Cook                        | CK        |
| Costa Rica                       | CR        |
| Côte d'Ivoire                    | CI        |
| Croatie                          | HR        |
| Cuba                             | CU        |
| Curaçao                          | CW        |
| Chypre                           | CY        |
| Tchéquie                         | CZ        |
| Danemark                         | DK        |
| Djibouti                         | DJ        |
| Dominique                        | DM        |
| République dominicaine           | DO        |
| Timor oriental                   | TL        |
| Équateur                         | EC        |
| Égypte                           | EG        |
| Salvador                         | SV        |
| Guinée équatoriale               | GQ        |
| Érythrée                         | ER        |
| Estonie                          | EE        |
| Eswatini                         | SZ        |
| Éthiopie                         | ET        |
| Îles Malouines                   | FK        |
| Îles Féroé                       | FO        |
| Fidji                            | FJ        |
| Finlande                         | FI        |
| France                           | FR        |
| Guyane française                 | GF        |
| Polynésie française              | PF        |
| Gabon                            | GA        |
| Gambie                           | GM        |
| Géorgie                          | GE        |
| Allemagne                        | DE        |
| Ghana                            | GH        |
| Gibraltar                        | GI        |
| Grèce                            | GR        |
| Groenland                        | GL        |
| Grenade                          | GD        |
| Guadeloupe                       | GP        |
| Guam                             | GU        |
| Guatemala                        | GT        |
| Guernesey                        | GG        |
| Guinée                           | GN        |
| Guinée-Bissau                    | GW        |
| Guyana                           | GY        |
| Haïti                            | HT        |
| Honduras                         | HN        |
| Hong Kong                        | HK        |
| Hongrie                          | HU        |
| Islande                          | IS        |
| Inde                             | IN        |
| Indonésie                        | ID        |
| Iran                             | IR        |
| Irak                             | IQ        |
| Irlande                          | IE        |
| Île de Man                       | IM        |
| Israël                           | IL        |
| Italie                           | IT        |
| Jamaïque                         | JM        |
| Japon                            | JP        |
| Jersey                           | JE        |
| Jordanie                         | JO        |
| Kazakhstan                       | KZ        |
| Kenya                            | KE        |
| Kiribati                         | KI        |
| Kosovo                           | XK        |
| Koweït                           | KW        |
| Kirghizistan                     | KG        |
| Laos                             | LA        |
| Lettonie                         | LV        |
| Liban                            | LB        |
| Lesotho                          | LS        |
| Libéria                          | LR        |
| Libye                            | LY        |
| Liechtenstein                    | LI        |
| Lituanie                         | LT        |
| Luxembourg                       | LU        |
| Macao                            | MO        |
| Madagascar                       | MG        |
| Malawi                           | MW        |
| Malaisie                         | MY        |
| Maldives                         | MV        |
| Mali                             | ML        |
| Malte                            | MT        |
| Îles Marshall                    | MH        |
| Martinique                       | MQ        |
| Mauritanie                       | MR        |
| Maurice                          | MU        |
| Mayotte                          | YT        |
| Mexique                          | MX        |
| Micronésie                       | FM        |
| Moldavie                         | MD        |
| Monaco                           | MC        |
| Mongolie                         | MN        |
| Monténégro                       | ME        |
| Montserrat                       | MS        |
| Maroc                            | MA        |
| Mozambique                       | MZ        |
| Myanmar                          | MM        |
| Namibie                          | NA        |
| Nauru                            | NR        |
| Népal                            | NP        |
| Pays-Bas                         | NL        |
| Nouvelle-Calédonie               | NC        |
| Nouvelle-Zélande                 | NZ        |
| Nicaragua                        | NI        |
| Niger                            | NE        |
| Nigeria                          | NG        |
| Corée du Nord                    | KP        |
| Macédoine du Nord                | MK        |
| Îles Mariannes du Nord           | MP        |
| Norvège                          | NO        |
| Oman                             | OM        |
| Pakistan                         | PK        |
| Palaos                           | PW        |
| Panama                           | PA        |
| Papouasie-Nouvelle-Guinée        | PG        |
| Paraguay                         | PY        |
| Pérou                            | PE        |
| Philippines                      | PH        |
| Pologne                          | PL        |
| Portugal                         | PT        |
| Porto Rico                       | PR        |
| Qatar                            | QA        |
| La Réunion                       | RE        |
| Roumanie                         | RO        |
| Russie                           | RU        |
| Rwanda                           | RW        |
| Sainte-Hélène                    | SH        |
| Saint-Kitts-et-Nevis             | KN        |
| Sainte-Lucie                     | LC        |
| Saint-Martin                     | MF        |
| Saint-Pierre-et-Miquelon         | PM        |
| Saint-Vincent-et-les-Grenadines  | VC        |
| Samoa                            | WS        |
| Saint-Marin                      | SM        |
| São Tomé-et-Príncipe             | ST        |
| Arabie saoudite                  | SA        |
| Sénégal                          | SN        |
| Serbie                           | RS        |
| Seychelles                       | SC        |
| Sierra Leone                     | SL        |
| Singapour                        | SG        |
| Saint-Martin                     | SX        |
| Slovaquie                        | SK        |
| Slovénie                         | SI        |
| Îles Salomon                     | SB        |
| Somalie                          | SO        |
| Afrique du Sud                   | ZA        |
| Corée du Sud                     | KR        |
| Soudan du Sud                    | SS        |
| Espagne                          | ES        |
| Sri Lanka                        | LK        |
| Saint-Barthélemy                 | BL        |
| Soudan                           | SD        |
| Suriname                         | SR        |
| Suède                            | SE        |
| Suisse                           | CH        |
| Syrie                            | SY        |
| Taïwan                           | TW        |
| Tadjikistan                      | TJ        |
| Tanzanie                         | TZ        |
| Thaïlande                        | TH        |
| Bahamas                          | BS        |
| Togo                             | TG        |
| Tonga                            | TO        |
| Trinité-et-Tobago                | TT        |
| Tunisie                          | TN        |
| Turquie                          | TR        |
| Turkménistan                     | TM        |
| Îles Turques-et-Caïques          | TC        |
| Tuvalu                           | TV        |
| Ouganda                          | UG        |
| Ukraine                          | UA        |
| Émirats arabes unis              | AE        |
| Royaume-Uni                      | GB        |
| États-Unis                       | US        |
| Uruguay                          | UY        |
| Îles Vierges américaines         | VI        |
| Ouzbékistan                      | UZ        |
| Vanuatu                          | VU        |
| Vatican                          | VA        |
| Venezuela                        | VE        |
| Viêt Nam                         | VN        |
| Wallis-et-Futuna                 | WF        |
| Yémen                            | YE        |
| Zambie                           | ZM        |
| Zimbabwe                         | ZW        |

## Autres notes

Information importante sur la facturation : chaque adresse IP traitée consomme un crédit. La facturation s'effectue par soumission de requête, que la réponse soit réussie ou non. Par conséquent, soumettre une adresse IP invalide comme « fda3346ds » déduira quand même un crédit de votre compte.