usersbox API
API usersbox полволяет вам получить доступ к обширному количеству данных (порядка 16 миллиардов документов).
Создание приложения
Перед началом работы вам необходимо получить токен. Для этого создайте приложение через бота (команда /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-адрес.
{
"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 (Integer) - радиус поиска в метрах от указанной точки
{
"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"
}
},
...
]
}
}
/lang/ru
Возвращает русский языковой пакет для полей документа, который включает около 1900 локализованных наименований.
{
"status": "success",
"data": {
"id": "ID",
"uid": "User ID",
"first_name": "Имя",
"last_name": "Фамилия",
"sex": "Пол",
"age": "Возраст",
// другие поля ...
}
}Тарифы на запросы
Приобрести запросы Вы можете внутри Telegram бота используя внутренний баланс (команду /api).
Тарификация методов
Стоимость метода зависит от его вычислительной сложности, так, обычный запрос будет стоить дешево, когда более сложный возрастает в цене.
- Метод
{database}/{collection}/search - Метод
/search - Метод
{database}/{collection}/nearbySearch - Метод
{database}/{collection}/explain - Метод
/explain - Метод
/{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) - оценке релевантности документа. Чем выше значение - тем боле вероятно документ соответствует результату поиска.
Статус коды ошибок
- code 1: Invalid access token.
- code 2: Missing access token.
- code 3: Rate limit.
- code 4: Not enough requests.
- code 100: Missing query parameter.
- code 101: Missing path parameter.
- code 102: Source not found.
- code 1000: Unknown Error.
{
"status": "error",
"error": {
"code": 1,
"message": "Invalid access token"
}
}FAQ (Ответы на вопросы)
Как пополнить баланс приложения?
Баланс можно перевести с вашего аккаунта. Для этого сначала надо пополнить баланс через команду /me, а потом выполнить перевод средств в приложение через команду /api
Почему у каждой базы разные поля?
Структура базы зависит от ее исходного вида. Мы стараемся придерживаться единой структуры и стиля наименования полей, однако для всех 900+ источников это сделать не всегда получается.
А расширенный поиск где?
В данный момент поиск через API работает только через наши источники. Расширенный поиск это отдельный сервис.
Будет ли regex?
Почему в ответе два поля count: обычный count и hitsCount?
Поле count показывает, сколько всего документов вернулось в response, в то время когда hitsCount показывает примерное кол-во документов во всей коллекции.
К примеру, ваш /explain запрос:
GET /emails/breach-compilation/[email protected] HTTP/1.1
В данном случае вы получите hits.count = 6363, потому-что в базе breach-compilation примерно 6363 документов, где содержится "[email protected]"
GET /emails/breach-compilation/[email protected] HTTP/1.1
В этом случае count = 25, т.к. максимальная выдача на одну базу равна 25.