Vai al contenuto principale
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

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