API экспорта базы объявлений

1. Авторизация

Все запросы требуют персональный API-токен. Создайте его в личном кабинете → раздел «API доступ». Токен показывается один раз при создании — сохраните его в надёжном месте.

Передавайте токен одним из способов:

• Заголовок Authorization: Bearer <ваш_токен> (рекомендуется)
• Заголовок X-API-Key: <ваш_токен>
• Параметр запроса ?token=<ваш_токен>

Базовый адрес API: https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai

2. Эндпоинты

3. Параметры фильтрации

Применимы к /api/v1/listings и /api/v1/listings/export. Все параметры необязательны и комбинируются логическим «И» (каждый сужает выборку). Незаполненные и неизвестные значения игнорируются.

Справочники значений

Тип сделки (type_id)

Автор (person_type)

Категории (category_id)

Источники (source_id)

Подтипы (object_category_id) — зависят от выбранной категории

4. Поля объявления (JSON)

5. Примеры

cURL — JSON

curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
  "https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai/api/v1/listings?type_id=1&city=Москва&price_to=10000000&limit=50"

cURL — выгрузка CSV

curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
  "https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai/api/v1/listings/export?format=csv&type_id=1&city=Москва" \
  -o listings.csv

cURL — выгрузка Excel

curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
  "https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai/api/v1/listings/export?format=xlsx" \
  -o listings.xlsx

Python

import requests

TOKEN = "ВАШ_ТОКЕН"
headers = {"Authorization": f"Bearer {TOKEN}"}

# Постранично JSON
resp = requests.get(
    "https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai/api/v1/listings",
    headers=headers,
    params={"type_id": 1, "city": "Москва", "limit": 100, "page": 1},
)
data = resp.json()
print(data["count"], "объявлений")
for item in data["items"]:
    print(item["id"], item["title"], item["price"])

# Выгрузка CSV в файл
csv_resp = requests.get(
    "https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai/api/v1/listings/export",
    headers=headers,
    params={"format": "csv", "type_id": 1},
)
with open("listings.csv", "wb") as f:
    f.write(csv_resp.content)

PHP

<?php

$token = 'ВАШ_ТОКЕН';
$base = 'https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai';

function apiRequest(string $url, string $token): string
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer {$token}"],
    ]);
    $response = curl_exec($ch);
    if ($response === false) {
        throw new RuntimeException(curl_error($ch));
    }
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status >= 400) {
        throw new RuntimeException("HTTP {$status}: {$response}");
    }
    return $response;
}

// Постранично JSON
$listingsUrl = $base . '/api/v1/listings?' . http_build_query([
    'type_id' => 1,
    'city' => 'Москва',
    'limit' => 100,
    'page' => 1,
]);
$data = json_decode(apiRequest($listingsUrl, $token), true);
echo $data['count'] . " объявлений\n";
foreach ($data['items'] as $item) {
    echo $item['id'] . ' ' . $item['title'] . ' ' . $item['price'] . "\n";
}

// Выгрузка CSV в файл
$exportUrl = $base . '/api/v1/listings/export?' . http_build_query([
    'format' => 'csv',
    'type_id' => 1,
]);
file_put_contents('listings.csv', apiRequest($exportUrl, $token));

Пример ответа JSON

{
  "count": 1240,
  "page": 1,
  "limit": 100,
  "pages": 13,
    "items": [
    {
      "id": 12345,
      "title": "2-комнатная квартира, 54 м²",
      "price": 8500000,
      "city": "Нижний Новгород",
      "internal_url": "https://xn----7sbhhdbjpbam7aecwwmpt.xn--p1ai/listing/12345-...",
      "url": "https://..."
    }
  ]
}

6. Ограничения и ошибки

• limit для JSON — максимум 1000 объявлений на страницу.
• Выгрузка файлом — максимум 5000 объявлений за запрос.
• 401 — токен не передан или недействителен.
• 400 — неверные параметры (например, неизвестный format).