> ## 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 Geolocation и Email Validation нужны разные ключи. Для аутентификации добавьте ключ к базовому 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 Cleariflow, поэтому ключ IP Geolocation не будет работать, например, с API проверки email.
</ParamField>

<ParamField query="ip_address" type="String">
  IP-адрес для геолокации. Поддерживаются IPv4 и IPv6. Если параметр не указан, сервис геолокализирует IP-адрес, с которого был сделан запрос.
</ParamField>

<ParamField query="fields" type="String">
  Список **верхнеуровневых** ключей для возврата через запятую (например, `?fields=country,security`). Для флагов VPN/прокси используйте `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">
  Почтовый индекс.
</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]">
  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 совпадает с базой прокси (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">
  Смещение часового пояса относительно 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">
  Флаг страны в виде эмодзи.
</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 и прокси указываются в `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-ответа. Для этого передайте в query-параметрах 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).

| Название страны               | Код страны |
| ----------------------------- | ---------- |
| Афганистан                    | AF         |
| Албания                       | AL         |
| Алжир                         | DZ         |
| Американское Самоа            | AS         |
| Андорра                       | AD         |
| Ангола                        | AO         |
| Ангилья                       | AI         |
| Антигуа и Барбуда             | AG         |
| Аргентина                     | AR         |
| Армения                       | AM         |
| Аруба                         | AW         |
| Австралия                     | AU         |
| Австрия                       | AT         |
| Азербайджан                   | AZ         |
| Бахрейн                       | BH         |
| Бангладеш                     | BD         |
| Барбадос                      | BB         |
| Беларусь                      | BY         |
| Бельгия                       | BE         |
| Белиз                         | BZ         |
| Бенин                         | BJ         |
| Бермуды                       | BM         |
| Бутан                         | BT         |
| Боливия                       | BO         |
| Босния и Герцеговина          | BA         |
| Ботсвана                      | BW         |
| Бразилия                      | BR         |
| Британские Виргинские острова | VG         |
| Бруней                        | BN         |
| Болгария                      | BG         |
| Буркина-Фасо                  | BF         |
| Бурунди                       | BI         |
| Кабо-Верде                    | CV         |
| Камбоджа                      | KH         |
| Камерун                       | CM         |
| Канада                        | CA         |
| Каймановы острова             | KY         |
| ЦАР                           | CF         |
| Чад                           | TD         |
| Чили                          | CL         |
| Китай                         | CN         |
| Колумбия                      | CO         |
| Коморы                        | KM         |
| Конго                         | CG         |
| ДР Конго                      | CD         |
| Острова Кука                  | CK         |
| Коста-Рика                    | CR         |
| Кот-д'Ивуар                   | CI         |
| Хорватия                      | HR         |
| Куба                          | CU         |
| Кюрасао                       | CW         |
| Кипр                          | CY         |
| Чехия                         | CZ         |
| Дания                         | DK         |
| Джибути                       | DJ         |
| Доминика                      | DM         |
| Доминиканская Республика      | DO         |
| Восточный Тимор               | TL         |
| Эквадор                       | EC         |
| Египет                        | EG         |
| Сальвадор                     | SV         |
| Экваториальная Гвинея         | GQ         |
| Эритрея                       | ER         |
| Эстония                       | EE         |
| Эсватини                      | SZ         |
| Эфиопия                       | ET         |
| Фолклендские острова          | FK         |
| Фарерские острова             | FO         |
| Фиджи                         | FJ         |
| Финляндия                     | FI         |
| Франция                       | FR         |
| Французская Гвиана            | GF         |
| Французская Полинезия         | PF         |
| Габон                         | GA         |
| Гамбия                        | GM         |
| Грузия                        | GE         |
| Германия                      | DE         |
| Гана                          | GH         |
| Гибралтар                     | GI         |
| Греция                        | GR         |
| Гренландия                    | GL         |
| Гренада                       | GD         |
| Гваделупа                     | GP         |
| Гуам                          | GU         |
| Гватемала                     | GT         |
| Гернси                        | GG         |
| Гвинея                        | GN         |
| Гвинея-Бисау                  | GW         |
| Гайана                        | GY         |
| Гаити                         | HT         |
| Гондурас                      | HN         |
| Гонконг                       | HK         |
| Венгрия                       | HU         |
| Исландия                      | IS         |
| Индия                         | IN         |
| Индонезия                     | ID         |
| Иран                          | IR         |
| Ирак                          | IQ         |
| Ирландия                      | IE         |
| Остров Мэн                    | IM         |
| Израиль                       | IL         |
| Италия                        | IT         |
| Ямайка                        | JM         |
| Япония                        | JP         |
| Джерси                        | JE         |
| Иордания                      | JO         |
| Казахстан                     | KZ         |
| Кения                         | KE         |
| Кирибати                      | KI         |
| Косово                        | XK         |
| Кувейт                        | KW         |
| Кыргызстан                    | KG         |
| Лаос                          | LA         |
| Латвия                        | LV         |
| Ливан                         | LB         |
| Лесото                        | LS         |
| Либерия                       | LR         |
| Ливия                         | LY         |
| Лихтенштейн                   | LI         |
| Литва                         | LT         |
| Люксембург                    | LU         |
| Макао                         | MO         |
| Мадагаскар                    | MG         |
| Малави                        | MW         |
| Малайзия                      | MY         |
| Мальдивы                      | MV         |
| Мали                          | ML         |
| Мальта                        | MT         |
| Маршалловы острова            | MH         |
| Мартиника                     | MQ         |
| Мавритания                    | MR         |
| Маврикий                      | MU         |
| Майотта                       | YT         |
| Мексика                       | MX         |
| Микронезия                    | FM         |
| Молдова                       | MD         |
| Монако                        | MC         |
| Монголия                      | MN         |
| Черногория                    | ME         |
| Монтсеррат                    | MS         |
| Марокко                       | MA         |
| Мозамбик                      | MZ         |
| Мьянма                        | MM         |
| Намибия                       | NA         |
| Науру                         | NR         |
| Непал                         | NP         |
| Нидерланды                    | NL         |
| Новая Каледония               | NC         |
| Новая Зеландия                | NZ         |
| Никарагуа                     | NI         |
| Нигер                         | NE         |
| Нигерия                       | NG         |
| КНДР                          | KP         |
| Северная Македония            | MK         |
| Северные Марианские острова   | MP         |
| Норвегия                      | NO         |
| Оман                          | OM         |
| Пакистан                      | PK         |
| Палау                         | PW         |
| Панама                        | PA         |
| Папуа — Новая Гвинея          | PG         |
| Парагвай                      | PY         |
| Перу                          | PE         |
| Филиппины                     | PH         |
| Польша                        | PL         |
| Португалия                    | PT         |
| Пуэрто-Рико                   | PR         |
| Катар                         | QA         |
| Реюньон                       | RE         |
| Румыния                       | RO         |
| Россия                        | RU         |
| Руанда                        | RW         |
| Остров Святой Елены           | SH         |
| Сент-Китс и Невис             | KN         |
| Сент-Люсия                    | LC         |
| Сен-Мартен                    | MF         |
| Сен-Пьер и Микелон            | PM         |
| Сент-Винсент и Гренадины      | VC         |
| Самоа                         | WS         |
| Сан-Марино                    | SM         |
| Сан-Томе и Принсипи           | ST         |
| Саудовская Аравия             | SA         |
| Сенегал                       | SN         |
| Сербия                        | RS         |
| Сейшелы                       | SC         |
| Сьерра-Леоне                  | SL         |
| Сингапур                      | SG         |
| Синт-Мартен                   | SX         |
| Словакия                      | SK         |
| Словения                      | SI         |
| Соломоновы острова            | SB         |
| Сомали                        | SO         |
| ЮАР                           | ZA         |
| Южная Корея                   | KR         |
| Южный Судан                   | SS         |
| Испания                       | ES         |
| Шри-Ланка                     | LK         |
| Сен-Бартелеми                 | BL         |
| Судан                         | SD         |
| Суринам                       | SR         |
| Швеция                        | SE         |
| Швейцария                     | CH         |
| Сирия                         | SY         |
| Тайвань                       | TW         |
| Таджикистан                   | TJ         |
| Танзания                      | TZ         |
| Таиланд                       | TH         |
| Багамы                        | BS         |
| Того                          | TG         |
| Тонга                         | TO         |
| Тринидад и Тобаго             | TT         |
| Тунис                         | TN         |
| Турция                        | TR         |
| Туркменистан                  | TM         |
| Тёркс и Кайкос                | TC         |
| Тувалу                        | TV         |
| Уганда                        | UG         |
| Украина                       | UA         |
| ОАЭ                           | AE         |
| Великобритания                | GB         |
| США                           | US         |
| Уругвай                       | UY         |
| Виргинские острова США        | VI         |
| Узбекистан                    | UZ         |
| Вануату                       | VU         |
| Ватикан                       | VA         |
| Венесуэла                     | VE         |
| Вьетнам                       | VN         |
| Уоллис и Футуна               | WF         |
| Йемен                         | YE         |
| Замбия                        | ZM         |
| Зимбабве                      | ZW         |

## Прочее

Важная информация по биллингу: каждый обработанный IP-адрес расходует один кредит. Списание происходит за запрос, независимо от успеха ответа. Поэтому даже передача невалидного IP вроде «fda3346ds» спишет один кредит с аккаунта.