API de géolocalisation IP

GET

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

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

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 :

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

Paramètres de requête

api_key

String

requis

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.

ip_address

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.

fields

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.

Paramètres de réponse

La réponse de l’API est renvoyée dans un format JSON universel et léger.

ip_address

String

L’adresse IP soumise pour géolocalisation.

city

String

Nom de la ville.

city_geoname_id

String

ID geoname de la ville.

region

String

État ou province dans lequel la ville est située.

region_iso_code

Char[2]

Code ISO 3166-2 de l’État ou de la province.

region_geoname_id

String

ID geoname de l’État ou de la province.

postal_code

String

Code postal.

country

String

Nom du pays.

country_code

Char[2]

Code ISO 3166-1 alpha-2 du pays.

country_geoname_id

String

ID geoname du pays.

country_is_eu

Boolean

Vrai si le pays est dans l’UE, faux sinon.

continent

String

Nom du continent.

continent_code

Char[2]

Code continent à 2 lettres : AF, AS, EU, NA, OC, SA, AN.

continent_geoname_id

String

ID geoname du continent.

longitude

Float

Valeur décimale de la longitude.

latitude

Float

Valeur décimale de la latitude.

security.is_vpn

Boolean

true lorsque l’IP correspond à la base de données des nœuds de sortie VPN (IP-to-VPN MMDB).

security.is_proxy

Boolean

true lorsque l’IP correspond à la base de données proxy (IP-to-VPN MMDB).

security.vpn_provider

String

Nom du service VPN depuis la MMDB (par exemple, NordVPN). Omis lorsque is_vpn est false.

timezone.name

String

Nom du fuseau horaire depuis la base de données IANA Time Zone.

timezone.abbreviation

String

Abréviation du fuseau horaire, également depuis la base de données IANA Time Zone.

timezone.gmt_offset

String

Décalage du fuseau horaire par rapport au temps moyen de Greenwich (GMT).

timezone.current_time

String

Heure actuelle dans le fuseau horaire local.

timezone.is_dst

Boolean

Vrai si la localisation est actuellement en heure d’été (DST).

flag.svg

String

Lien vers une version hébergée du drapeau du pays au format SVG.

flag.png

String

Lien vers une version hébergée du drapeau du pays au format PNG.

flag.emoji

String

Drapeau du pays sous forme d’emoji.

flag.unicode

String

Drapeau du pays en unicode.

currency.currency_name

String

Nom de la devise.

currency.currency_code

String

Code de la devise au format ISO 4217.

connection.connection_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.

connection.autonomous_system_number

Uint32

Numéro de système autonome.

connection.autonomous_system_organization

String

Nom de l’organisation du système autonome.

connection.isp_name

String

Nom du fournisseur d’accès Internet (FAI).

connection.organization_name

String

Nom de l’organisation.

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 :

{
    "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.

$.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.

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.

IntroductionL'API de taux de change Cleariflow offre des capacités de conversion de devises en temps réel via une interface JSON RESTful moderne et rationalisée, prenant en charge plus de 80 devises mondiales.

API de géolocalisation IP

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

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

​Premiers pas

​Architecture REST

​Sécurité HTTPS

​Versionnage de l’API

​Authentification par clé API

​URL de base

​Endpoint de géolocalisation

​Paramètres de requête

​Paramètres de réponse

​Limiter les champs de réponse

​Cas d’utilisation

​Géolocaliser un visiteur de site web

​Codes de réponse et d’erreur

​Codes pays

​Autres notes

Premiers pas

Architecture REST

Sécurité HTTPS

Versionnage de l’API

Authentification par clé API

URL de base

Endpoint de géolocalisation

Paramètres de requête

Paramètres de réponse

Limiter les champs de réponse

Cas d’utilisation

Géolocaliser un visiteur de site web

Codes de réponse et d’erreur

Codes pays

Autres notes