# API Сегментации (Фильтры) ## createFilter `POST` `https://api.pushwoosh.com/json/1.3/createFilter` Создает новый фильтр. **Тело запроса** | Название | Обязательно | Тип | Описание | | ---------------------------------------------------- | ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | auth\* | Да | string | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) из Панели управления Pushwoosh. | | name\* | Да | string | [Название фильтра](/ru/developer/api-reference/api-identifiers/#segment--filter-name). | | filter\_expression\* | Да | string |

Выражение, составленное в соответствии с правилами языка Сегментации.
Пример: T("City", eq, "Madrid") для сегментации пользователей, чей город — Мадрид.

| | application | Нет | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code). Этот параметр используется только с High-Speed Setup; в противном случае его следует опустить. | | expiration\_date | Нет | string | Срок действия фильтра. Фильтр будет автоматически удален в указанную дату, если он не используется в Пресете или RSS-ленте. | **200** ```json { "status_code": 200, "status_message": "OK", "response": { "name": "filter name" } } ``` **Пример** ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", "name": "City = Madrid", "filter_expression": "T(\"City\", eq, \"Madrid\")", "application": "B18XX-XXXXX", "expiration_date": "2025-01-01" } } // создание Фильтров для часовых поясов { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // Токен доступа API из Панели управления Pushwoosh "name": "Timezone Filter", "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])" } } ``` ## listFilters `POST` `https://api.pushwoosh.com/json/1.3/listFilters` Возвращает список доступных сегментов (фильтров) с их условиями. **Тело запроса** | Название | Обязательно | Тип | Описание | | --------------------------------------------- | ----------- | ------ | ---------------------------------------------- | | auth\* | Да | string | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) из Панели управления Pushwoosh. | | application\* | Да | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) | **200** ```json { "status_code": 200, "status_message": "OK", "response": { "filters": [{ "code": "52551-F2F42", "name": "City = Madrid", "filter_expression": "T(\"City\", eq, \"madrid\")", "expiration_date": "2025-01-01", "application": "B18XX-XXXXX" }] } } ``` **Пример** ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", "application": "B18XX-XXXXX" } } ``` ## deleteFilter `POST` `https://api.pushwoosh.com/json/1.3/deleteFilter` Удаляет существующий фильтр. **Тело запроса** | Название | Тип | Описание | | -------------------------------------- | ------ | ---------------------------------------------- | | auth\* | string | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) из Панели управления Pushwoosh. | | name\* | string | [Название фильтра](/ru/developer/api-reference/api-identifiers/#segment--filter-name). | ```json { "status_code": 200, "status_message": "OK", "response": null } ``` ```json title="Пример" { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // Токен доступа API из Панели управления Pushwoosh "name": "filter name" } } ``` ## exportSegment `POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment` Запланированный запрос. Экспортирует список подписчиков, которые подпадают под указанные условия Фильтра. **Тело запроса** | Название
| Обязательно
| Тип | Описание | |----------------------------|------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | auth\* | Да | string | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) из Панели управления Pushwoosh. | | filterExpression\* | Да | string | Условия фильтра | | exportData | Нет | array | Данные для экспорта. Возможные значения: `"hwids"`, `"push_tokens"`, `"users"`, `"tags"`, `"location"`. Включение `"location"` добавляет столбцы `Latitude` и `Longitude` в экспортируемый CSV. Если `exportData` опущен, `Latitude` и `Longitude` включаются в экспорт по умолчанию. | | filterCode | Нет | string | Готовый [код фильтра](/ru/developer/api-reference/api-identifiers/#segment--filter-code), можно использовать вместо `filterExpression`. Можно получить из API `/listFilters` или из адресной строки вашего браузера при просмотре фильтра в Панели управления. | | applicationCode | Обязательно, если вы используете `filterExpression` или `filterCode`. | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) | | generateExport | Нет | boolean | По умолчанию установлено `true`, и ответ содержит ссылку для скачивания файла. Если false, в ответе будет отправлено только количество устройств. | | format | Нет | string | Устанавливает формат экспортируемого файла: "csv" или "json\_each\_line". Если не указано, генерируется CSV-файл. | | tagsList | Нет | array | Указывает [теги](/ru/developer/api-reference/api-identifiers/#tag) для экспорта. Чтобы получить только определенные теги, массив "exportData" должен содержать значение "tags". | | includeWithoutTokens | Нет | boolean | Установите `true`, чтобы включить пользователей без push-токенов в экспортируемый файл. По умолчанию `false`. | ```json { "task_id": "177458" } ``` ```json title="Пример" { "auth": "yxoPUlwqm…………pIyEX4H", // обязательно. Токен доступа API из Панели управления Pushwoosh "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // условия фильтра, синтаксис см. в руководстве по языку Сегментации "filterCode": "12345-67890", // готовый код фильтра, можно использовать вместо filterExpression "applicationCode": "00000-AAAAA", // Обязательно, если вы используете `filterExpression` или `filterCode`. Код приложения Pushwoosh. Можно получить из API-запроса /listFilters или из адресной строки браузера при просмотре фильтра в Панели управления. "generateExport": true, // если false, в ответе будет только количество устройств; по умолчанию ответ содержит ссылку для скачивания CSV-файла "format": "json_each_line", // формат файла для представления данных: "csv" – скачивается .csv-файл; "json" – JSON-файл со всеми экспортированными устройствами; или "json_each_line" – строка JSON для каждого устройства. Если не указано, по умолчанию используется формат CSV. "exportData": ["hwids", "tags"], // необязательно. Данные для экспорта. Возможные значения: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys" "tagsList": ["Name", "Level"], // необязательно. Указывает теги для экспорта. Чтобы получить только определенные теги, в массиве "exportData" должно быть значение "tags", либо массив "exportData" должен быть пустым. "includeWithoutTokens": true // необязательно. Установите true, чтобы включить пользователей без push-токенов в экспортируемый файл. По умолчанию false. } ``` Например, чтобы экспортировать всех подписчиков определенного приложения, используйте следующие условия Фильтра: ```json { "auth": "yxoPUlwqm…………pIyEX4H", // Токен доступа API из Панели управления Pushwoosh "filterExpression": "A(\"AAAAA-BBBBB\")", // Выражение фильтра, ссылающееся на сегмент приложения "applicationCode": "AAAAA-BBBBB" // Обязательный код приложения Pushwoosh } ``` ## exportSegment results `POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment/result` **Получает ссылку на CSV с результатами /exportSegment.** **Тело запроса** | Название | Тип | Описание | | ------------------------------------------ | ------ | -------------------------------------------------------- | | auth\* | String | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) из Панели управления Pushwoosh. | | task\_id\* | String | Идентификатор, полученный в вашем ответе на `/exportSegment`. | ```json { "devicesCount": "24735", "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip", "status": "completed" } ``` Передайте «**task\_id**», полученный в ответе на ваш запрос `/exportSegment`, в теле запроса `/exportSegment/result`. В ответе на запрос `/exportSegment/result` вы получите параметр «filename». Перейдите по ссылке, указанной в значении этого параметра, чтобы автоматически загрузить ZIP-архив. Распакуйте архив, чтобы получить CSV или JSON файл (в зависимости от «format», указанного в вашем запросе), содержащий данные устройств. С 3 апреля 2025 года для скачивания файла потребуется авторизация: - При скачивании через **браузер** просто войдите в **Панель управления Pushwoosh**, чтобы получить доступ. - При скачивании через **серверное ПО** включите в ваш запрос следующий заголовок: `Authorization: Token YOUR_API_TOKEN` Если вы укажете «exportData» в вашем запросе `/exportSegment`, скачанный файл будет содержать только запрошенные данные. По умолчанию файл содержит следующие данные пользователя: | **Поле** | Описание | Пример значения | | ------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------ | | Hwid | [Аппаратный ID устройства](/ru/developer/api-reference/api-identifiers/#hardware-id) | 01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8 | | User ID | [User ID](/ru/developer/api-reference/api-identifiers/#user-id), связывающий устройство с определенным пользователем. Если User ID не назначен, используется HWID. | user8192 | | Push Token | Уникальный идентификатор, присваиваемый устройству шлюзами облачных сообщений. [Узнать больше](/ru/developer/api-reference/api-identifiers/#push-token) | eeeb2fd7....0fc3547 | | Type | Тип платформы (целое число). | 1 | | Type (humanized) | Тип платформы (строка). | iOS | | Age | Значение тега по умолчанию Age. | 29 | | ApplicationVersion | Значение тега по умолчанию Application Version. | 1.12.0.0 | | City | Значение тега по умолчанию City. | us, boston | | TagName | Значение тега, созданного в вашем аккаунте. | TagValue |