> ## 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 di geolocalizzazione IP

> L'API di geolocalizzazione IP di Cleariflow è un'API RESTful JSON veloce, efficiente e moderna che identifica la posizione e altri dettagli degli indirizzi IP in oltre 190 paesi.

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:

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

### Parametri della richiesta

<ParamField query="api_key" type="String" required>
  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.
</ParamField>

<ParamField query="ip_address" type="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.
</ParamField>

<ParamField query="fields" type="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.
</ParamField>

### Parametri della risposta

La risposta API viene restituita in un [formato JSON](https://www.json.org/json-en.html) universale e leggero.

<ResponseField name="ip_address" type="String">
  L'indirizzo IP inviato per la geolocalizzazione.
</ResponseField>

<ResponseField name="city" type="String">
  Nome della città.
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  ID geoname della città.
</ResponseField>

<ResponseField name="region" type="String">
  Stato o provincia in cui si trova la città.
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  Codice ISO 3166-2 dello stato o della provincia.
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  ID geoname dello stato o della provincia.
</ResponseField>

<ResponseField name="postal_code" type="String">
  CAP o codice postale.
</ResponseField>

<ResponseField name="country" type="String">
  Nome del paese.
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  Codice ISO 3166-1 alpha-2 del paese.
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  ID geoname del paese.
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  `true` se il paese è nell'UE, `false` in caso contrario.
</ResponseField>

<ResponseField name="continent" type="String">
  Nome del continente.
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  Codice continente a 2 lettere: AF, AS, EU, NA, OC, SA, AN.
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  ID geoname del continente.
</ResponseField>

<ResponseField name="longitude" type="Float">
  Valore decimale della longitudine.
</ResponseField>

<ResponseField name="latitude" type="Float">
  Valore decimale della latitudine.
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  `true` quando l'IP corrisponde al database enumerato dei nodi di uscita VPN (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  `true` quando l'IP corrisponde al database proxy (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  Nome del servizio VPN dal MMDB (ad esempio, `NordVPN`). Omesso quando `is_vpn` è `false`.
</ResponseField>

<ResponseField name="timezone.name" type="String">
  Nome del fuso orario dal database IANA Time Zone.
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  Abbreviazione del fuso orario, anch'essa dal database IANA Time Zone.
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  Offset del fuso orario rispetto al Greenwich Mean Time (GMT).
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  Ora corrente nel fuso orario locale.
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  `true` se la località è attualmente in ora legale (DST).
</ResponseField>

<ResponseField name="flag.svg" type="String">
  Link a una versione ospitata della bandiera del paese in formato SVG.
</ResponseField>

<ResponseField name="flag.png" type="String">
  Link a una versione ospitata della bandiera del paese in formato PNG.
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  Bandiera del paese come emoji.
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Bandiera del paese in unicode.
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  Nome della valuta.
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  Codice della valuta in formato ISO 4217.
</ResponseField>

<ResponseField name="connection.connection_type" 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.
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  Numero del sistema autonomo.
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  Nome dell'organizzazione del sistema autonomo.
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  Nome dell'Internet Service Provider (ISP).
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  Nome dell'organizzazione.
</ResponseField>

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

```json theme={"system"}
{
    "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.

```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);
})
```

È 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](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing).

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