usersbox API

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

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

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

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

/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-запросы?

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

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

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