• Последние обновления
• Создание приложения
• Список доступных методов
• /getMe
• /sources
• /{database}/{collection}/search
• /search
• /{database}/{collection}/explain
• /explain
• /{database}/{collection}/nearbySearch
• /{database}/{collection}/sample
• /database/{collection}/schema
• /lang/ru
• Тарифы на запросы
• Тарификация методов
• Доступные типы
• App
• Source
• Document
• Статус коды ошибок
• FAQ (Ответы на вопросы)
• Как пополнить баланс приложения?
• Почему у каждой базы разные поля?
• Как форматировать запросы?
• Будет ли regex?
• Почему в ответе два поля count и hitsCount?
• Какой лимит на count?
• Можно ли выполнять POST-запросы?
• Есть ли ограничения на количество запросов?

API usersbox полволяет вам получить доступ к обширному количеству данных (порядка 20 миллиардов документов).

Последние обновления

usersbox API 1.1 (22 Марта, 2025)

• Добавлен параметр count к методу /search
• Добавлен метод /schema

usersbox API 1.2 (26 Мая, 2025)

• Обновлены лимиты для /explain

Создание приложения

Перед началом работы вам необходимо получить токен. Для этого создайте приложение через бота (команда /api > создать приложение).

Все запросы к API серверу посылаются через метод GET. Токен должен быть указан в заголовоке (Header) Authorization. Все запросы должны посылаться к домену api.usersbox.ru/v1/{method_name}

Пример:

GET /v1/getMe HTTP/1.1
Host: api.usersbox.ru
Authorization: eyJhbGciOiJIUzI1Ni.eyJjcmVhdG…

Список доступных методов

Мы поддерживаем метод GET для запроса. Все ответы содержат JSON-обьект, в котором есть несколько полей:

• status (String) - Статус ответа: success или error
• data (Any) - Обьект ответа. Обычно список элементов
• error (Dict) - В случае ошибки возвращает code и message

/getMe

Возвращает базовую информацию о текущем приложении. Используйте этот метод для тестирования приложения.

Пример успешного ответа:

{
    "status": "success",
    "data": {
        "_id": ...,
        "title": "Morales Publisher",
        "token": "...",
        "created_at": "Jan 10, 2024, 12:05:00 PM",
        "is_active": true,
        "balance": 150.5,
        "owner": {
            "user_id": ...,
            "bot_id": ...,
        }
    }
}

/sources

Возвращает список всех источников данных.

Пример успешного ответа:

{
    "status": "success",
    "data": {
        "count": 981,
        "items": [
            {
                "database": "cdek",
                "collection": "full",
                "size": 31919315138,
                "count": 205663278,
                "title": "🚚 CDEK [2022]"
            },
            {
                "database": "100realt",
                "collection": "parsing_2021",
                "size": 5394439345,
                "count": 4916799,
                "title": "🏠\t Парсинг «100realt.ru» [2021]"
            },
            // остальные 979 источников ...
       ]
    }
}

/{database}/{collection}/search

Выполняет поиск по выбранной базе. Возвращает первые 25 найденных документов. {database} и {collection} должны быть определены согласно информации, полученной из метода /sources. Структура полей документов в ответе может варьироваться, так как она зависит от структуры конкретной базы данных.

Принимает параметры:

• q (String) - поисковый запрос, может быть любой строкой. Например, номер телефона, email, имя пользователя, IP-адрес.
• count (Int) - кол-во возвращаемых элементов. От 25 до 500

Пример успешного ответа:

{
    "status": "success",
    "data": {
        "count": 4,
        "items": [
            {
                "_id": 3212868,
                "full_name": "Василий Иванов Максимович",
                "birth_date": "30.08.1945",
                "phone": "+79177840591",
                "_score": 7.08725643157959
            },
            {
                "_id": 4349339,
                "full_name": "Василий Иванов Максимович",
                "birth_date": "20.05.1968",
                "phone": "+79065499712",
                "_score": 7.08725643157959
            },
            // другие документы ...
        ]
    }
}

Пример ответа без результатов:

{
    "status": "success",
    "data": {
        "count": 0,
        "items": []
    }
}

/search

Выполняет поиск сразу во всем источникам одновременно. Используйте этот метод для быстрого поиска по всей нашей базе. Лимит выдачи ограничен 25 документами на одну базу.

Принимает параметры:

• q (String) - поисковый запрос, может быть любой строкой. Например, номер телефона, email, имя пользователя, IP-адрес.

Пример успешного ответа:

{
    "status": "success",
    "count": 5
    "items": [
        {
            "source": {
                "database": "2berega_ru",
                "collection": "clients"
            },
            "hits": {
                "hitsCount": 1,
                "count": 1,
                "items": [...]
            }
        },
        {
            "source": {
                "database": "yandex",
                "collection": "eda"
            },
            "hits": {
                "hitsCount": 1,
                "count": 1,
                "items": [...]
            }
        },
        ...
    ]
}
 

Пример ответа без результатов:

{
    "status": "success",
    "data": {
        "count": 0,
        "items": []
    }
}

/{database}/{collection}/explain

Возвращает кол-во найденных документов в выбранной базе.

Принимает параметры:

• q (String) - поисковый запрос, может быть любой строкой. Например, номер телефона, email, имя пользователя, IP-адрес.

Пример успешного ответа:

{
    "status": "success",
    "data": {
        "count": 11458
    }
}

/explain

Выполняет поиск по всей базе и возвращает кол-во документов. Используйте этот метод, если вам нужно проверить цель на утечки, но сами данные не нужны.

• q (String) - поисковый запрос, может быть любой строкой. Например, номер телефона, email, имя пользователя, IP-адрес.

Пример успешного запроса:

{
    "status": "success",
    "data": {
        "count": 15,
        "items": [
            {
                "source": {
                    "database": "500px_com",
                    "collection": "users"
                },
                "hits": {
                    "count": 1
                }
            },
            {
                "source": {
                    "database": "appen_com",
                    "collection": "users"
                },
                "hits": {
                    "count": 1
                }
            },
            // остальные элементы ...
        ]
    }
}

Пример ответа без результатов:

{
    "status": "success",
    "data": {
        "count": 0,
        "items": []
    }
}

/{database}/{collection}/nearbySearch

Выполняет поиск документов, которые находятся в заданном радиусе от указанной геолокации. Только некоторые коллекции поддерживают этот метод:

delivery_club/part1
delivery_club/part2
yandex/eda
avito/ads
auchan/users_2023

Принимает параметры:

• lat (Double) - широта центральной точки
• lon (Double) - долгота центральной точки
• radius (Int) - радиус поиска в метрах от указанной точки
• count (Int) - кол-во возвращаемых элементов. От 25 до 500

Пример успешного ответа:

{
    "status": "success",
    "data": {
        "hitsCount": 1000,
        "tooManyDocs": true,
        "count": 25,
        "items": [
            {
                "user_id": 6538242,
                "first_name": "Станислав",
                "phone": "+79112778424",
                "address": {
                    "city": "Санкт-Петербург",
                    "street": "Гороховая улица",
                    "house": "4",
                    "floor": "4",
                    "office": "28",
                    "doorcode": "3460#",
                    "comment": "арка 0625#",
                    "latitude": "59.936322",
                    "longitude": "30.311550"
                },
                "_score": 1.0
            },
            {...}
        ]
    }
}

/{database}/{collection}/sample

Отображает первые 15 документов из выбранной коллекции. Используйте его, чтобы посмотреть структуру полей

Пример успешного ответа:

{
   "status":"success",
   "data":{
      "count":15,
      "items":[
         {
            "_id":492033988,
            "user_id":225889705,
            "yandex_uid":"1219928845",
            "first_name":"mrozovmail.ru",
            "phone":"+79088468484",
            "amount":427,
            "currency":"RUB",
            "app":"eda_iphone",
            "user_agent":"ios(5.5.0)",
            "payment":{
               "service":"Apple Pay Yandex Eda",
            },
            "address":{
               "city":"Москва, поселение Щаповское",
               "street":"коттеджный посёлок Европейская Долина",
               "house":"1",
               "office":"148",
               "reliable":1,
               "latitude":"55.430539",
               "longitude":"37.389167"
            }
         },
         ...
      ]
   }
}

/database/{collection}/schema

Возвращает JSON-схему документов коллекции на основе первых 5000 записей. Используется для анализа структуры полей.

Пример успешного ответа:

{
    "status": "success",
    "data": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
            "_id": {
                "type": "integer"
            },
            "first_name": {
                "type": "string"
            },
            "last_name": {
                "type": "string"
            },
            "sex": {
                "type": "integer"
            },

/lang/ru

Возвращает русский языковой пакет для полей документа, который включает около 2600 локализованных наименований.

Пример успешного запроса:

{
    "status": "success",
    "data": {
        "id": "ID",
        "uid": "User ID",
        "first_name": "Имя",
        "last_name": "Фамилия",
        "sex": "Пол",
        "age": "Возраст",
        // другие поля ...
    }
}

Тарифы на запросы

Приобрести запросы Вы можете внутри Telegram бота используя внутренний баланс (команду /api).

Тарификация методов

Стоимость запроса зависит от вычислительной сложности метода. Простые запросы стоят дешевле, сложные — дороже. Некоторые методы тарифицируются за каждый возвращаемый документ.

• Метод {database}/{collection}/search
• Стоимость: 0.005 ₽ за один документ
• Минимальная плата: даже если по запросу ничего не найдено или найдено менее 25 документов, списывается минимальная стоимость за 25 документов (25 * 0.005 = 0.125 ₽).
• Максимальная плата: при count=500 и наличии достаточного количества результатов, составит 500 * 0.005 = 2.5 ₽
• Метод /search
• Стоимость: 2.5 ₽
• Метод {database}/{collection}/nearbySearch
• Аналогично /{database}/{collection}/search
• Метод {database}/{collection}/explain
• Стоимость: Бесплатно
• Лимиты: 300 запросов в минуту
• Метод /explain
• Стоимость: Бесплатно
• Лимиты: 300 запросов в минуту
• Метод /{database}/{collection}sample
• Стоимость: Бесплатно
• Метод /getMe
• Стоимость: Бесплатно
• Метод /sources
• Стоимость: Бесплатно

Доступные типы

App

• title (String) - название приложения.
• token (String) - секретный ключ доступа.
• created_at (String) - дата создания (МСК).
• is_active (Bool) - статус активации.
• balance (Float) - баланс в рублях.

Source

• database (String) - название базы.
• collection (String) - название коллекции.
• size (Int) - размер базы в байтах.
• title (String) - человеко-читаемое имя базы.

Document

• ... (Any) - основные поля документа.
• _score (Float) - оценке релевантности документа. Чем выше значение - тем боле вероятно документ соответствует результату поиска.

Explanation

• count (Long) - кол-во найденных документов.

Статус коды ошибок

• code 1: Invalid access token.
• Токен недействителен или просрочен. Проверьте заголовок Authorization.
• code 2: Missing access token.
• Токен не передан. Добавьте заголовок Authorization в запрос.
• code 3: Rate limit exceeded. Retry after N seconds.
• Превышен лимит запросов. Подождите N секунд и попробуйте снова
• code 4: Not enough requests.
• На балансе приложения недостаточно средств. Пополните баланс
• code 100: Missing query parameter.
• Не передан параметр q в GET запросе.
• code 101: Missing path parameter.
• Не указаны параметры пути — например, {database} или {collection}.
• code 102: Source not found.
• Источник не найден. Убедитесь, что база и коллекция существуют (см. /sources).
• code 1000: Unknown Error.
• Внутренняя ошибка сервера. Повторите запрос позже или обратитесь в поддержку.

Пример ошибки:

{
    "status": "error",
    "error": {
        "code": 1,
        "message": "Invalid access token"
    }
}

FAQ (Ответы на вопросы)

Как пополнить баланс приложения?

Баланс можно перевести с вашего аккаунта. Для этого сначала надо пополнить баланс через команду /me, а потом выполнить перевод средств в приложение через команду /api

Почему у каждой базы разные поля?

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

Как форматировать запросы?

Для точных результатов предварительно форматируйте ваш запрос:

• Телефоны: формат E.164
• Даты рождения: формат ДД.ММ.ГГГГ

Будет ли regex?

Вероятно чуть позже, да.

Почему в ответе два поля count и hitsCount?

• count - сколько документов вернулось в ответе (items.size)
• hitsCount - примерное общее число совпадений в коллекции

Какой лимит на count?

count может быть от 25 до 500. Если вы передаёте значение вне этого диапазона — оно будет автоматически приведено к ближайшему допустимому значению.

Можно ли выполнять POST-запросы?

Нет. На данный момент API работает только по GET-методу.

Есть ли ограничения на количество запросов?

Для /explain и /{database}/{collection}/explain есть лимиты - 300 запросов в минуту. При достижении этого лимиты вы получите ошибку Rate limit exceeded. Retry after N seconds

Возможно, вы слышали о такой платформе, как Cryptomus — она предоставляет удобный шлюз для работы с криптовалютными сетями, такие как TRON, BTC, ETH, TON.

К концу 2023 года с нами связался менеджер и предложил интегрировать Cryptomus в usersbox. Мы согласились и стали использовать его для выдачи кошельков для пополнения, где каждому пользователю выдавался индивидуальный адрес. Выглядело это так:

Все было прекрасно, пока нас не заблокировали.

День Х: Блокировка перед выводом

27 августа, когда под конец месяца накопилась приличная сумма для вывода, Cryptomus блокирует мерчант:

Cryptomus заботливо напоминает, что в случае чего пишите в поддержку:

Не паникуем и пишем в поддержку.

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

Исходя из графика tronscan, видим аномальные пики, которые свидетельствуют о том, что 27-28 августа средства не выводились, как это было прежде:

Не будем строить конспирологических теорий на основе одних лишь графиков tronscan, а заглянем в их чат. Тут я обнаружил несколько людей, которые жалуются на замороженные средства:

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

Предлагаю посмотреть недавние отзывы на разных площадках. И тут мы тоже видим, что люди столкнулись с заморозкой средств.

Cryptomus блокирует средства некоторых кошельков, а в ответ лишь шаблонные фразы в стиле «нам очень жаль, что такое произошло». Новая стратегия заработка?

Хатико в поисках AML

Единственный ответ, который мы получили спустя 5 дней, - один из сотрудников предположил, что дело касается AML (Anti-money Laundering)

В таком случае пробуем проверить некоторые последние входящие транзакции на наш марчант. Возьмем популярный для этого инструмент - AMLBot.

Он умеет определять уровень риска кошелька / транзакции.

И действительно, я нашел одну подозрительную транзакцию в BTC (1$) с риском 75%. Однако, все остальные были в порядке.

Какой итог?

После придании огласки нам разблокировали средства. Однако, мы до сих пор ждем, когда поддержка даст конкретный ответ на эту ситуацию.