Skip to main content
GET
API di geolocalizzazione IP
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

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:
Questa rappresenta una richiesta riuscita, che restituisce l’indirizzo IP e i dettagli associati di seguito:

Parametri della richiesta

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.
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.
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.
String
L’indirizzo IP inviato per la geolocalizzazione.
String
Nome della città.
String
ID geoname della città.
String
Stato o provincia in cui si trova la città.
Char[2]
Codice ISO 3166-2 dello stato o della provincia.
String
ID geoname dello stato o della provincia.
String
CAP o codice postale.
String
Nome del paese.
Char[2]
Codice ISO 3166-1 alpha-2 del paese.
String
ID geoname del paese.
Boolean
true se il paese è nell’UE, false in caso contrario.
String
Nome del continente.
Char[2]
Codice continente a 2 lettere: AF, AS, EU, NA, OC, SA, AN.
String
ID geoname del continente.
Float
Valore decimale della longitudine.
Float
Valore decimale della latitudine.
Boolean
true quando l’IP corrisponde al database enumerato dei nodi di uscita VPN (IP-to-VPN MMDB).
Boolean
true quando l’IP corrisponde al database proxy (IP-to-VPN MMDB).
String
Nome del servizio VPN dal MMDB (ad esempio, NordVPN). Omesso quando is_vpn è false.
String
Nome del fuso orario dal database IANA Time Zone.
String
Abbreviazione del fuso orario, anch’essa dal database IANA Time Zone.
String
Offset del fuso orario rispetto al Greenwich Mean Time (GMT).
String
Ora corrente nel fuso orario locale.
Boolean
true se la località è attualmente in ora legale (DST).
String
Link a una versione ospitata della bandiera del paese in formato SVG.
String
Link a una versione ospitata della bandiera del paese in formato PNG.
String
Bandiera del paese come emoji.
String
Bandiera del paese in unicode.
String
Nome della valuta.
String
Codice della valuta in formato ISO 4217.
String
Dedotto dal nome dell’organizzazione ASN (ad esempio, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN e proxy sono riportati in security, non qui.
Uint32
Numero del sistema autonomo.
String
Nome dell’organizzazione del sistema autonomo.
String
Nome dell’Internet Service Provider (ISP).
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:
La risposta avrà questo aspetto:

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

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.

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.