API di geolocalizzazione 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 funziona con notevole semplicità: basta fornire la chiave API insieme a un indirizzo IP e riceverai dati di localizzazione completi inclusi codici postali, nomi delle città, informazioni regionali, dettagli sul paese e coordinate precise di latitudine/longitudine.

Per iniziare

Architettura REST

Come tutte le API Cleariflow, l’API di geolocalizzazione IP segue i principi REST. Utilizza URL prevedibili e orientati alle risorse e i codici di stato HTTP per indicare gli errori.

Sicurezza HTTPS

Tutte le comunicazioni con l’API di geolocalizzazione IP devono essere protette con protocolli TLS 1.2 o superiore.

Versionamento API

Tutte le API Cleariflow incorporano il versionamento. L’API di geolocalizzazione IP opera attualmente sulla versione 1.

Autenticazione con chiave API

La tua chiave API funge da credenziale di autenticazione univoca per accedere all’API di geolocalizzazione IP di Cleariflow. È importante notare che ogni API Cleariflow richiede una chiave API distinta, quindi avrai bisogno di chiavi separate per servizi diversi come geolocalizzazione IP e validazione email. Per autenticare le richieste, aggiungi la chiave API all’URL di base.

URL di base

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

Endpoint di geolocalizzazione

L’API di geolocalizzazione IP di Cleariflow richiede solo la tua chiave API univoca e rileva automaticamente l’indirizzo IP del client richiedente. In alternativa, puoi includere il parametro “ip_address” per specificare un IP particolare da analizzare:

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

Questa rappresenta una richiesta riuscita, che restituisce l’indirizzo IP e i dettagli associati di seguito:

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

Parametri della richiesta

api_key

String

obbligatorio

La tua chiave API univoca. Nota che ogni utente ha chiavi API univoche per ciascuna delle API Cleariflow, quindi la chiave dell’API di geolocalizzazione IP non funzionerà per l’API di validazione email, ad esempio.

ip_address

String

L’indirizzo IP da geolocalizzare. Sono supportati sia indirizzi IPv4 che IPv6. Nota che se lasci vuoto questo parametro, il servizio geolocalizzerà l’indirizzo IP da cui è stata effettuata la richiesta.

fields

String

Elenco separato da virgole di chiavi di primo livello da restituire (ad esempio, ?fields=country,security). Per includere i flag VPN/proxy, usa security — viene restituito l’intero oggetto (is_vpn, is_proxy e vpn_provider quando presente). Chiavi annidate come is_vpn da sole non sono supportate.

Parametri della risposta

La risposta API viene restituita in un formato JSON universale e leggero.

ip_address

String

L’indirizzo IP inviato per la geolocalizzazione.

city

String

Nome della città.

city_geoname_id

String

ID geoname della città.

region

String

Stato o provincia in cui si trova la città.

region_iso_code

Char[2]

Codice ISO 3166-2 dello stato o della provincia.

region_geoname_id

String

ID geoname dello stato o della provincia.

postal_code

String

CAP o codice postale.

country

String

Nome del paese.

country_code

Char[2]

Codice ISO 3166-1 alpha-2 del paese.

country_geoname_id

String

ID geoname del paese.

country_is_eu

Boolean

true se il paese è nell’UE, false in caso contrario.

continent

String

Nome del continente.

continent_code

Char[2]

Codice continente a 2 lettere: AF, AS, EU, NA, OC, SA, AN.

continent_geoname_id

String

ID geoname del continente.

longitude

Float

Valore decimale della longitudine.

latitude

Float

Valore decimale della latitudine.

security.is_vpn

Boolean

true quando l’IP corrisponde al database enumerato dei nodi di uscita VPN (IP-to-VPN MMDB).

security.is_proxy

Boolean

true quando l’IP corrisponde al database proxy (IP-to-VPN MMDB).

security.vpn_provider

String

Nome del servizio VPN dal MMDB (ad esempio, NordVPN). Omesso quando is_vpn è false.

timezone.name

String

Nome del fuso orario dal database IANA Time Zone.

timezone.abbreviation

String

Abbreviazione del fuso orario, anch’essa dal database IANA Time Zone.

timezone.gmt_offset

String

Offset del fuso orario rispetto al Greenwich Mean Time (GMT).

timezone.current_time

String

Ora corrente nel fuso orario locale.

timezone.is_dst

Boolean

true se la località è attualmente in ora legale (DST).

flag.svg

String

Link a una versione ospitata della bandiera del paese in formato SVG.

flag.png

String

Link a una versione ospitata della bandiera del paese in formato PNG.

flag.emoji

String

Bandiera del paese come emoji.

flag.unicode

String

Bandiera del paese in unicode.

currency.currency_name

String

Nome della valuta.

currency.currency_code

String

Codice della valuta in formato ISO 4217.

connection.connection_type

String

Dedotto dal nome dell’organizzazione ASN (ad esempio, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN e proxy sono riportati in security, non qui.

connection.autonomous_system_number

Uint32

Numero del sistema autonomo.

connection.autonomous_system_organization

String

Nome dell’organizzazione del sistema autonomo.

connection.isp_name

String

Nome dell’Internet Service Provider (ISP).

connection.organization_name

String

Nome dell’organizzazione.

Limitare i campi della risposta

Puoi scegliere di ricevere solo alcuni campi dalla risposta JSON. Per farlo, puoi includere un valore fields nei parametri di query con un elenco separato da virgole delle chiavi di primo livello che desideri ricevere. Ad esempio, una richiesta per ottenere solo paese e città di un IP avrà questo aspetto:

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

La risposta avrà questo aspetto:

{
    "city": "Vienna",
    "country": "Austria"
}

Casi d’uso

Geolocalizzare un visitatore del sito web

Per richiedere la geolocalizzazione da un indirizzo IP, includi semplicemente la tua chiave API univoca nel modello seguente. Nota che non è necessario conoscere l’IP del visitatore per effettuare la richiesta.

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

È tutto ciò che serve per ottenere la geolocalizzazione e altri dati da un visitatore! C’è un solo parametro obbligatorio: la tua chiave API univoca.

Codici di risposta ed errore

Ogni volta che effettui una richiesta che fallisce per qualche motivo, viene restituito un errore anch’esso in formato JSON. Gli errori includono un codice e una descrizione, che puoi trovare in dettaglio di seguito.

Code	Type	Details
200	OK	Tutto ha funzionato come previsto.
204	OK	Non ci sono dati di localizzazione per l’IP inviato.
400	Bad request	Richiesta non valida.
401	Unauthorized	La richiesta non è stata accettata. Di solito a causa di una chiave API mancante o errata.
422	Quota reached	La richiesta è stata interrotta per crediti API insufficienti. (Piani gratuiti)
429	Too many requests	La richiesta è stata interrotta perché è stato raggiunto il numero di richieste consentite al secondo. Succede sui piani gratuiti poiché le richieste sono limitate a 1 al secondo.
500	Internal server error	La richiesta non è stata completata a causa di un errore lato server.
503	Service unavailable	Il server non era disponibile.

Codici paese

Di seguito un elenco dei codici paese ISO 3166 Alpha 2 a due lettere usati nella risposta. Visualizza questo elenco in un CSV.

Nome paese	Codice paese
Afghanistan	AF
Albania	AL
Algeria	DZ
American Samoa	AS
Andorra	AD
Angola	AO
Anguilla	AI
Antigua and Barbuda	AG
Argentina	AR
Armenia	AM
Aruba	AW
Australia	AU
Austria	AT
Azerbaijan	AZ
Bahrain	BH
Bangladesh	BD
Barbados	BB
Belarus	BY
Belgium	BE
Belize	BZ
Benin	BJ
Bermuda	BM
Bhutan	BT
Bolivia	BO
Bosnia and Herzegovina	BA
Botswana	BW
Brazil	BR
British Virgin Islands	VG
Brunei	BN
Bulgaria	BG
Burkina Faso	BF
Burundi	BI
Cabo Verde	CV
Cambodia	KH
Cameroon	CM
Canada	CA
Cayman Islands	KY
Central African Republic	CF
Chad	TD
Chile	CL
China	CN
Colombia	CO
Comoros	KM
Congo	CG
Congo Democratic Republic	CD
Cook Islands	CK
Costa Rica	CR
Cote d’Ivoire	CI
Croatia	HR
Cuba	CU
Curaçao	CW
Cyprus	CY
Czechia	CZ
Denmark	DK
Djibouti	DJ
Dominica	DM
Dominican Republic	DO
East Timor	TL
Ecuador	EC
Egypt	EG
El Salvador	SV
Equatorial Guinea	GQ
Eritrea	ER
Estonia	EE
eSwatini	SZ
Ethiopia	ET
Falkland Islands	FK
Faroe Islands	FO
Fiji	FJ
Finland	FI
France	FR
French Guiana	GF
French Polynesia	PF
Gabon	GA
Gambia	GM
Georgia	GE
Germany	DE
Ghana	GH
Gibraltar	GI
Greece	GR
Greenland	GL
Grenada	GD
Guadeloupe	GP
Guam	GU
Guatemala	GT
Guernsey	GG
Guinea	GN
Guinea-Bissau	GW
Guyana	GY
Haiti	HT
Honduras	HN
Hong Kong	HK
Hungary	HU
Iceland	IS
India	IN
Indonesia	ID
Iran	IR
Iraq	IQ
Ireland	IE
Isle of Man	IM
Israel	IL
Italy	IT
Jamaica	JM
Japan	JP
Jersey	JE
Jordan	JO
Kazakhstan	KZ
Kenya	KE
Kiribati	KI
Kosovo	XK
Kuwait	KW
Kyrgyzstan	KG
Laos	LA
Latvia	LV
Lebanon	LB
Lesotho	LS
Liberia	LR
Libya	LY
Liechtenstein	LI
Lithuania	LT
Luxembourg	LU
Macau	MO
Madagascar	MG
Malawi	MW
Malaysia	MY
Maldives	MV
Mali	ML
Malta	MT
Marshall Islands	MH
Martinique	MQ
Mauritania	MR
Mauritius	MU
Mayotte	YT
Mexico	MX
Micronesia	FM
Moldova	MD
Monaco	MC
Mongolia	MN
Montenegro	ME
Montserrat	MS
Morocco	MA
Mozambique	MZ
Myanmar	MM
Namibia	NA
Nauru	NR
Nepal	NP
Netherlands	NL
New Caledonia	NC
New Zealand	NZ
Nicaragua	NI
Niger	NE
Nigeria	NG
North Korea	KP
North Macedonia	MK
Northern Mariana Islands	MP
Norway	NO
Oman	OM
Pakistan	PK
Palau	PW
Panama	PA
Papua New Guinea	PG
Paraguay	PY
Peru	PE
Philippines	PH
Poland	PL
Portugal	PT
Puerto Rico	PR
Qatar	QA
Reunion	RE
Romania	RO
Russia	RU
Rwanda	RW
Saint Helena	SH
Saint Kitts and Nevis	KN
Saint Lucia	LC
Saint Martin	MF
Saint Pierre and Miquelon	PM
Saint Vincent and the Grenadines	VC
Samoa	WS
San Marino	SM
Sao Tome and Principe	ST
Saudi Arabia	SA
Senegal	SN
Serbia	RS
Seychelles	SC
Sierra Leone	SL
Singapore	SG
Sint Maarten	SX
Slovakia	SK
Slovenia	SI
Solomon Islands	SB
Somalia	SO
South Africa	ZA
South Korea	KR
South Sudan	SS
Spain	ES
Sri Lanka	LK
St. Barts	BL
Sudan	SD
Suriname	SR
Sweden	SE
Switzerland	CH
Syria	SY
Taiwan	TW
Tajikistan	TJ
Tanzania	TZ
Thailand	TH
The Bahamas	BS
Togo	TG
Tonga	TO
Trinidad and Tobago	TT
Tunisia	TN
Turkey	TR
Turkmenistan	TM
Turks and Caicos Islands	TC
Tuvalu	TV
Uganda	UG
Ukraine	UA
United Arab Emirates	AE
United Kingdom	GB
United States	US
Uruguay	UY
US Virgin Islands	VI
Uzbekistan	UZ
Vanuatu	VU
Vatican City (Holy See)	VA
Venezuela	VE
Vietnam	VN
Wallis and Futuna	WF
Yemen	YE
Zambia	ZM
Zimbabwe	ZW

Altre note

Informazioni importanti sulla fatturazione: ogni indirizzo IP elaborato consuma un credito. La fatturazione avviene per ogni richiesta inviata, indipendentemente dal fatto che la risposta sia riuscita. Pertanto, anche l’invio di un indirizzo IP non valido come “fda3346ds” dedurrà comunque un credito dal tuo account.

IntroduzioneL'API tassi di cambio di Cleariflow offre capacità di conversione valutaria in tempo reale tramite un'interfaccia RESTful JSON snella e moderna, con supporto per oltre 80 valute globali, tassi live, dati storici e strumenti di conversione istantanea.

API di geolocalizzazione 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
    }
}

​Per iniziare

​Architettura REST

​Sicurezza HTTPS

​Versionamento API

​Autenticazione con chiave API

​URL di base

​Endpoint di geolocalizzazione

​Parametri della richiesta

​Parametri della risposta

​Limitare i campi della risposta

​Casi d’uso

​Geolocalizzare un visitatore del sito web

​Codici di risposta ed errore

​Codici paese

​Altre note

Per iniziare

Architettura REST

Sicurezza HTTPS

Versionamento API

Autenticazione con chiave API

URL di base

Endpoint di geolocalizzazione

Parametri della richiesta

Parametri della risposta

Limitare i campi della risposta

Casi d’uso

Geolocalizzare un visitatore del sito web

Codici di risposta ed errore

Codici paese

Altre note