> For the complete documentation index, see [llms.txt](https://docs.iexexchanger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iexexchanger.com/learn/2.-nastroiki/04-geoip.md).

# GeoIP

Настройте локальные и внешние GeoIP-провайдеры, приоритет, кэш, обновления и диагностику

## Что вы получите

Система определяет страну и город по публичному IP через доступные провайдеры, быстро отвечает из кэша и продолжает работу при временном отказе одного источника. Секреты внешних сервисов сохранены отдельно, а результат подтверждён тестовым запросом и диагностикой.

Откройте **«Настройки» — «Общие настройки» — «Дополнительно» — «GeoIP»**. Для страницы требуется отдельное право на настройки GeoIP.

## Сначала выберите источники

| Провайдер        | Тип             | Что подготовить                                  |
| ---------------- | --------------- | ------------------------------------------------ |
| MaxMind GeoLite2 | База на сервере | Account ID, лицензионный ключ и загруженная база |
| DB-IP Lite       | База на сервере | Загруженная база и видимая атрибуция на сайте    |
| IPLocate.io      | Внешний API     | API-ключ и допустимый лимит запросов             |
| IP2Location.io   | Внешний API     | API-ключ и допустимый лимит запросов             |

Начните хотя бы с одного готового локального источника. Внешний API добавляйте как осознанный резерв или источник дополнительных данных после проверки условий провайдера, приватности, лимитов и стоимости.

{% hint style="warning" %}
Не включайте DB-IP Lite до размещения на публичном сайте видимой ссылки **«IP Geolocation by DB-IP»** и подтверждения атрибуции в панели. Не отмечайте условие выполненным, если ссылка существует только в черновике страницы.
{% endhint %}

## Настройте вкладку «Основное»

Для обычного рабочего режима:

* включите **«Определять страну и город по IP»**;
* оставьте включёнными кэширование, проверку и дополнение данных и ускорение списков IP;
* оставьте **«Временно не обращаться к провайдерам»** выключенным;
* выберите **«Продолжить и записать ошибку в журнал»**, если местоположение не найдено;
* используйте **«Учитывать доверенные прокси»**, если инфраструктура настроена штатно;
* пропускайте частные и зарезервированные IP;
* не включайте подробный режим постоянно без задачи диагностики.

Язык названий стран и городов берётся из основной настройки клиентского сайта. Отдельный язык GeoIP выбирать не нужно.

{% hint style="danger" %}
Режим **«Остановить операцию с ошибкой»** способен превратить отказ GeoIP в отказ клиентского процесса. Не используйте его как стартовое значение без отдельного требования риска и проверенного резервного провайдера.
{% endhint %}

## Подключите провайдеры

{% stepper %}
{% step %}

### Проверьте готовность локальных баз

Откройте вкладку **«Провайдеры»**. Для MaxMind и DB-IP панель сама показывает **«База доступна»** или **«База не установлена»**. Не включайте отсутствующую базу как будто она готова.
{% endstep %}

{% step %}

### Сохраните данные MaxMind

Нажмите **«Настроить доступ»**, укажите Account ID и лицензионный ключ. После сохранения секрет полностью не отображается. Затем загрузите базы на вкладке **«Обновления»** или подтвердите уже найденные файлы.
{% endstep %}

{% step %}

### Подтвердите DB-IP только после атрибуции

Убедитесь, что публичная ссылка видна посетителю, включите подтверждение атрибуции и только затем разрешите провайдер.
{% endstep %}

{% step %}

### Добавьте внешний API при необходимости

Для IPLocate.io или IP2Location.io сохраните ключ через отдельный диалог. Пустое поле при следующем открытии означает, что секрет скрыт, а не обязательно удалён; ориентируйтесь на признак **«Данные сохранены»**.
{% endstep %}

{% step %}

### Выполните тест каждого включённого источника

Укажите принадлежащий вам публичный IP, выберите полную геолокацию, страну или ASN и нажмите **«Проверить»**. Тест внешнего API расходует запрос из лимита провайдера.
{% endstep %}
{% endstepper %}

## Задайте стратегию

На вкладке **«Стратегия»** выберите **«Сначала установленные базы»**, включите **«Переключение провайдеров»** и перетащите источники в утверждённом порядке.

**«Объединять результаты»** обращается к следующим источникам, когда первому ответу не хватает полей. На старте оставьте объединение выключенным, если полный состав данных не нужен: оно увеличивает число запросов и усложняет разбор источника результата.

```mermaid
flowchart LR
    A["Публичный IP"] --> B["Первый готовый провайдер"]
    B -->|"Ответ найден"| C["Кеш и результат"]
    B -->|"Ошибка или пусто"| D["Следующий провайдер"]
    D --> C
```

## Не меняйте кэш без причины

На вкладке **«Кеш»** обычно достаточно:

* хранить результаты только для публичных IP;
* использовать основное хранилище приложения;
* оставить служебный префикс, сроки хранения, блокировку и лимит быстрого кэша по умолчанию;
* держать дополнительное быстрое кэширование включённым.

Очистка кэша GeoIP не очищает остальные разделы. Используйте её после смены провайдера, обновления базы или доказанного устаревшего результата, а не как регулярное действие.

## Оставьте защиту от сбоев

На вкладке **«Отказоустойчивость»** включённая автоматическая пауза временно пропускает источник после серии ошибок. Оставьте порог, окно, время паузы, таймауты, повторы и ограничение одинаковых предупреждений по умолчанию, если специалист не измерил другую потребность.

Кнопка **«Снять временную паузу»** не исправляет провайдера. Сначала устраните ошибку базы, ключа или сети, затем выполните тест и только после этого сбросьте защитное состояние.

## Настройте обновление локальных баз

{% tabs %}
{% tab title="Вручную" %}
На вкладке **«Обновления»** выберите готовый локальный источник и нажмите **«Обновить сейчас»**. MaxMind требует сохранённых данных доступа, DB-IP — подтверждённой атрибуции.
{% endtab %}

{% tab title="По расписанию" %}
Включите автообновление, выберите MaxMind и/или DB-IP, интервал в днях и час UTC. Убедитесь, что планировщик работает и выбранное окно не конфликтует с обслуживанием сервера.
{% endtab %}
{% endtabs %}

Система скачивает локальные базы с предусмотренных источников, проверяет новый файл и заменяет его без ручного редактирования путей. После обновления проверьте дату успеха и повторите тест.

## Завершите диагностикой

1. Откройте вкладку **«Диагностика»**.
2. Убедитесь, что хотя бы один включённый провайдер доступен.
3. Проверьте последнюю успешную работу, задержку и отсутствие необъяснённой временной паузы.
4. Сверьте состояние кэша и историю обновления локальных баз.
5. Выполните тест по собственному публичному IP.
6. Создайте новую контрольную клиентскую сессию и проверьте места панели, где проект использует географию посетителя.

GeoIP является вспомогательным сигналом и не доказывает личность, резидентство или право клиента на операцию. Юридические и риск-решения не должны основываться только на определённой стране IP.

## Этап завершён, если

* [ ] страницу открывает только роль с нужным правом;
* [ ] готов хотя бы один включённый провайдер;
* [ ] секреты сохранены через отдельные защищённые поля;
* [ ] DB-IP включён только после публичной атрибуции;
* [ ] локальные источники стоят раньше внешних либо другой порядок обоснован;
* [ ] переключение провайдеров и автоматическая пауза при сбоях включены;
* [ ] частные и зарезервированные IP не отправляются провайдерам;
* [ ] тест выполнен по разрешённому публичному IP;
* [ ] расписание обновления подтверждено либо назначено ручное обновление;
* [ ] диагностика показывает готовый источник и понятное состояние кэша.

Условия поставщиков сверяйте по их актуальным материалам: [обновление баз MaxMind](https://dev.maxmind.com/geoip/updating-databases/), [лицензия и атрибуция DB-IP Lite](https://db-ip.com/db/lite.php), [аутентификация IPLocate.io](https://www.iplocate.io/docs/getting-started/authentication) и [API IP2Location.io](https://www.ip2location.io/ip2location-documentation).

После GeoIP переходите к [кодам валют](/learn/3.-valyuty-i-dengi/01-currency-codes.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.iexexchanger.com/learn/2.-nastroiki/04-geoip.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.