> ## 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 de geolocalização IP

> Obtenha dados completos de localização para qualquer endereço IP no mundo. Ideal para analytics, prevenção de fraude, localização de conteúdo e aplicações de segurança.

A API funciona com notável simplicidade: basta fornecer a sua chave API juntamente com um endereço IP e receberá dados de localização abrangentes, incluindo códigos postais, nomes de cidades, informações regionais, detalhes do país e coordenadas precisas de latitude/longitude.

## Primeiros passos

### Arquitetura REST

Tal como todas as APIs Cleariflow, a API de geolocalização IP segue os princípios REST. Utiliza URLs previsíveis e orientadas a recursos e códigos de estado HTTP para indicar erros.

### Segurança HTTPS

Todas as comunicações com a API de geolocalização IP devem ser protegidas com TLS 1.2 ou superior.

### Versionamento da API

Todas as APIs Cleariflow incorporam versionamento. A API de geolocalização IP opera atualmente na Versão 1.

### Autenticação com chave API

A sua chave API serve como credencial de autenticação única para aceder à API de geolocalização IP da Cleariflow. Note que cada API Cleariflow requer uma chave API distinta, pelo que precisará de chaves separadas para geolocalização IP e validação de email. Para autenticar os seus pedidos, anexe a chave API à URL base.

### URL base

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

### Endpoint de geolocalização

A API de geolocalização IP da Cleariflow requer apenas a sua chave API única e deteta automaticamente o endereço IP do cliente que faz o pedido. Em alternativa, pode incluir o parâmetro `ip_address` para especificar um IP particular para análise:

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

Isto representa um pedido bem-sucedido, devolvendo o endereço IP e os detalhes associados abaixo:

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

### Parâmetros de pedido

<ParamField query="api_key" type="String" required>
  A sua chave API única. Note que cada utilizador tem chaves API únicas para cada API Cleariflow — a sua chave da API de geolocalização IP não funcionará para a API de validação de email, por exemplo.
</ParamField>

<ParamField query="ip_address" type="String">
  O endereço IP a geolocalizar. Endereços IPv4 e IPv6 são suportados. Se deixar este parâmetro em branco, o serviço geolocaliza o endereço IP de onde o pedido foi feito.
</ParamField>

<ParamField query="fields" type="String">
  Lista separada por vírgulas de chaves de **nível superior** a devolver (por exemplo, `?fields=country,security`). Para incluir flags VPN/proxy, utilize `security` — o objeto completo é devolvido (`is_vpn`, `is_proxy` e `vpn_provider` quando presente). Chaves aninhadas como apenas `is_vpn` não são suportadas.
</ParamField>

### Parâmetros de resposta

A resposta da API é devolvida num [formato JSON](https://www.json.org/json-en.html) universal e leve.

<ResponseField name="ip_address" type="String">
  O endereço IP enviado para geolocalização.
</ResponseField>

<ResponseField name="city" type="String">
  Nome da cidade.
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  ID Geoname da cidade.
</ResponseField>

<ResponseField name="region" type="String">
  Estado ou província onde a cidade se localiza.
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  Código ISO 3166-2 do estado ou província.
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  ID Geoname do estado ou província.
</ResponseField>

<ResponseField name="postal_code" type="String">
  Código postal.
</ResponseField>

<ResponseField name="country" type="String">
  Nome do país.
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  Código ISO 3166-1 alpha-2 do país.
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  ID Geoname do país.
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  `true` se o país pertence à UE, `false` caso contrário.
</ResponseField>

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

<ResponseField name="continent_code" type="Char[2]">
  Código de continente de 2 letras: AF, AS, EU, NA, OC, SA, AN.
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  ID Geoname do continente.
</ResponseField>

<ResponseField name="longitude" type="Float">
  Decimal da longitude.
</ResponseField>

<ResponseField name="latitude" type="Float">
  Decimal da latitude.
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  `true` quando o IP corresponde à base de dados enumerada de nós de saída VPN (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  `true` quando o IP corresponde à base de dados de proxy (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  Nome do serviço VPN da MMDB (por exemplo, `NordVPN`). Omitido quando `is_vpn` é `false`.
</ResponseField>

<ResponseField name="timezone.name" type="String">
  Nome do fuso horário da IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  Abreviatura do fuso horário, também da IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  Offset do fuso horário em relação ao Greenwich Mean Time (GMT).
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  Hora atual no fuso horário local.
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  `true` se a localização está atualmente em horário de verão (DST).
</ResponseField>

<ResponseField name="flag.svg" type="String">
  Ligação a uma versão alojada da bandeira do país em formato SVG.
</ResponseField>

<ResponseField name="flag.png" type="String">
  Ligação a uma versão alojada da bandeira do país em formato PNG.
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  Bandeira do país como emoji.
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Bandeira do país em unicode.
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  Nome da moeda.
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  Código da moeda no formato ISO 4217.
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  Inferido a partir do nome da organização ASN (por exemplo, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN e proxy são reportados em `security`, não aqui.
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  Número do Autonomous System.
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  Nome da organização do Autonomous System.
</ResponseField>

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

<ResponseField name="connection.organization_name" type="String">
  Nome da organização.
</ResponseField>

### Limitar campos de resposta

Pode optar por receber apenas alguns campos da resposta JSON. Para isso, inclua um valor `fields` nos parâmetros de consulta com uma lista separada por vírgulas das chaves de nível superior que pretende receber.

Por exemplo, um pedido para obter apenas o país e a cidade de um IP terá este aspeto:

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

A resposta terá este aspeto:

```json theme={"system"}
{
    "city": "Vienna",
    "country": "Austria"
}
```

## Casos de uso

### Geolocalizar um visitante do website

Para solicitar a geolocalização de um endereço IP, inclua simplesmente a sua chave API única no modelo abaixo.

Note que não precisa de conhecer o IP do visitante para fazer o pedido.

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

É tudo o que precisa para obter a geolocalização e outros dados de um visitante! Há apenas um parâmetro obrigatório: a sua chave API única.

## Códigos de resposta e erro

Sempre que um pedido falha por algum motivo, é devolvido um erro também em formato JSON. Os erros incluem um código e uma descrição, que pode consultar em detalhe abaixo.

| Code | Type                  | Detalhes                                                                                                                                                                  |
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Tudo funcionou como esperado.                                                                                                                                             |
| 204  | OK                    | Não existem dados de localização para o IP enviado.                                                                                                                       |
| 400  | Bad request           | Pedido inválido.                                                                                                                                                          |
| 401  | Unauthorized          | O pedido não foi aceite — normalmente devido a uma chave API em falta ou incorreta.                                                                                       |
| 422  | Quota reached         | O pedido foi abortado devido a créditos API insuficientes (planos gratuitos).                                                                                             |
| 429  | Too many requests     | O pedido foi abortado porque foi atingido o número de pedidos permitidos por segundo. Isto acontece em planos gratuitos, pois os pedidos estão limitados a 1 por segundo. |
| 500  | Internal server error | O pedido não pôde ser concluído devido a um erro no servidor.                                                                                                             |
| 503  | Service unavailable   | O servidor estava indisponível.                                                                                                                                           |

## Códigos de país

Abaixo está uma lista de códigos de país ISO 3166 Alpha 2 de duas letras utilizados na resposta. Consulte esta lista em [CSV](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing).

| Nome do país                     | Código do país |
| -------------------------------- | -------------- |
| 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             |

## Outras notas

Informação importante de faturação: cada endereço IP processado consome um crédito. A faturação ocorre por pedido submetido, independentemente de a resposta ser bem-sucedida. Portanto, mesmo submeter um endereço IP inválido como "fda3346ds" deduzirá um crédito da sua conta.