> ## 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 геолокації IP

> API геолокації IP Cleariflow — швидкий, ефективний, сучасний RESTful JSON API, який визначає місцезнаходження та інші деталі IP-адрес у понад 190 країнах.

API працює надзвичайно просто: передайте API-ключ разом із IP-адресою — і ви отримаєте повні дані про місцезнаходження, включаючи поштові індекси, назви міст, регіональну інформацію, дані про країну та точні координати широти/довготи.

## Початок роботи

### REST-архітектура

Як і всі API Cleariflow, API геолокації IP дотримується принципів REST. Воно використовує передбачувані URL, орієнтовані на ресурси, та HTTP-коди статусу для позначення помилок.

### Безпека HTTPS

Усі з'єднання з API геолокації IP мають бути захищені протоколами TLS 1.2 або вище.

### Версіонування API

Усі API Cleariflow мають версії. API геолокації IP наразі працює у версії 1.

### Автентифікація за API-ключем

API-ключ є унікальним обліковим даним для доступу до API геолокації IP Cleariflow. Важливо: кожен API Cleariflow потребує окремого ключа, тому для різних сервісів, як-от геолокація IP і перевірка email, потрібні різні ключі. Для автентифікації запитів додайте API-ключ до базового URL.

### Базовий URL

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

### Ендпоінт геолокації

API геолокації IP Cleariflow потребує лише вашого унікального API-ключа і автоматично визначає IP-адресу клієнта, що надсилає запит. Альтернативно можна передати параметр «ip\_address», щоб вказати конкретну IP для аналізу:

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

Це успішний запит — нижче повертаються IP-адреса та пов'язані дані:

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

### Параметри запиту

<ParamField query="api_key" type="String" required>
  Ваш унікальний API-ключ. Зверніть увагу: у кожного користувача є унікальні API-ключі для кожного API Cleariflow, тому ключ IP Geolocation не працюватиме для Email Validation API, наприклад.
</ParamField>

<ParamField query="ip_address" type="String">
  IP-адреса для геолокації. Підтримуються адреси IPv4 і IPv6. Якщо параметр не вказано, сервіс геолокує IP-адресу, з якої надійшов запит.
</ParamField>

<ParamField query="fields" type="String">
  Список **верхньорівневих** ключів через кому (наприклад, `?fields=country,security`). Для VPN/proxy використовуйте `security` — повертається весь об'єкт (`is_vpn`, `is_proxy` і `vpn_provider`, якщо є). Вкладені ключі на кшталт лише `is_vpn` не підтримуються.
</ParamField>

### Параметри відповіді

Відповідь API повертається у універсальному та легкому форматі [JSON](https://www.json.org/json-en.html).

<ResponseField name="ip_address" type="String">
  IP-адреса, передана для геолокації.
</ResponseField>

<ResponseField name="city" type="String">
  Назва міста.
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  Geoname ID міста.
</ResponseField>

<ResponseField name="region" type="String">
  Штат або провінція, де знаходиться місто.
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  ISO 3166-2 код штату або провінції.
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  Geoname ID штату або провінції.
</ResponseField>

<ResponseField name="postal_code" type="String">
  ZIP або поштовий індекс.
</ResponseField>

<ResponseField name="country" type="String">
  Назва країни.
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  ISO 3166-1 alpha-2 код країни.
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  Geoname ID країни.
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  true, якщо країна в ЄС, false — якщо ні.
</ResponseField>

<ResponseField name="continent" type="String">
  Назва континенту.
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  Дволітерний код континенту: AF, AS, EU, NA, OC, SA, AN.
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  Geoname ID континенту.
</ResponseField>

<ResponseField name="longitude" type="Float">
  Довгота у десятковому форматі.
</ResponseField>

<ResponseField name="latitude" type="Float">
  Широта у десятковому форматі.
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  `true`, коли IP відповідає базі VPN exit-node (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  `true`, коли IP відповідає базі proxy (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  Назва VPN-сервісу з MMDB (наприклад, `NordVPN`). Пропускається, коли `is_vpn` — `false`.
</ResponseField>

<ResponseField name="timezone.name" type="String">
  Назва часового поясу з IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  Абревіатура часового поясу з IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  Зміщення часового поясу від Greenwich Mean Time (GMT).
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  Поточний час у локальному часовому поясі.
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  true, якщо локація наразі в літньому часі (DST).
</ResponseField>

<ResponseField name="flag.svg" type="String">
  Посилання на розміщений прапор країни у форматі SVG.
</ResponseField>

<ResponseField name="flag.png" type="String">
  Посилання на розміщений прапор країни у форматі PNG.
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  Прапор країни у вигляді emoji.
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Прапор країни в unicode.
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  Назва валюти.
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  Код валюти у форматі ISO 4217.
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  Визначається з назви ASN-організації (наприклад, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN і proxy повідомляються в `security`, а не тут.
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  Номер автономної системи.
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  Назва організації автономної системи.
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  Назва інтернет-провайдера (ISP).
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  Назва організації.
</ResponseField>

### Обмеження полів відповіді

Можна отримати лише кілька полів з JSON-відповіді. Для цього передайте параметр fields зі списком верхньорівневих ключів через кому.

Наприклад, запит лише на країну та місто IP виглядатиме так:

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

Відповідь виглядатиме так:

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

## Сценарії використання

### Геолокація відвідувача сайту

Щоб отримати геолокацію за IP-адресою, просто передайте унікальний API-ключ у шаблоні нижче.

Зверніть увагу: для запиту не потрібно знати IP відвідувача.

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

Цього достатньо, щоб отримати геолокацію та інші дані відвідувача! Єдиний обов'язковий параметр — ваш унікальний API-ключ.

## Коди відповідей і помилок

Якщо запит не вдається, помилка також повертається у форматі JSON з кодом і описом, детально наведеними нижче.

| Code | Type                  | Details                                                                                            |
| ---- | --------------------- | -------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Усе працювало як очікувалося.                                                                      |
| 204  | OK                    | Немає даних про місцезнаходження для переданої IP-адреси.                                          |
| 400  | Bad request           | Некоректний запит.                                                                                 |
| 401  | Unauthorized          | Запит неприйнятний. Зазвичай через відсутній або неправильний API-ключ.                            |
| 422  | Quota reached         | Запит перервано через недостатню кількість API-кредитів. (Безкоштовні тарифи)                      |
| 429  | Too many requests     | Запит перервано через досягнення ліміту запитів на секунду. На безкоштовних тарифах — 1 запит/сек. |
| 500  | Internal server error | Запит не може бути виконаний через помилку на сервері.                                             |
| 503  | Service unavailable   | Сервер був недоступний.                                                                            |

## Коди країн

Нижче наведено список дволітерних ISO 3166 Alpha 2 кодів країн, що використовуються у відповіді. Переглянути список у [CSV](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing).

| Назва країни                     | Код країни |
| -------------------------------- | ---------- |
| 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         |

## Інші примітки

Важлива інформація про тарифікацію: кожна оброблена IP-адреса списує один кредит. Тарифікація відбувається за запит, незалежно від успішності відповіді. Тому навіть передача недійсної IP-адреси на кшталт «fda3346ds» все одно списує один кредит.