Документация

Ключ

Ключ выдаёт @fuckparserbot, кнопка «🔑 API». Он нужен в заголовке X-API-Key везде, кроме GET /v1/health. «♻️ Перевыпустить ключ» сразу выключает старый.

HEADERS = {"X-API-Key": "fp_ВАШ_КЛЮЧ"}

Задача

• POST /v1/tasks только создаёт задачу и возвращает её task.id. Объявлений в этом ответе нет. Повтор с теми же фильтрами, пока задача жива, вернёт тот же id.
• GET /v1/tasks/{id}/ads отдаёт объявления: только новые с прошлого запроса. Новую задачу не запускает.
• Ответ потерялся: повтори с repeat=1, придёт та же порция.
• Задача живёт 30 минут или до limit объявлений.
• Нет GET к задаче 3 минуты: она останавливается сама, на случай если скрипт упал.
• Закончилась: task.status станет done, причина в task.reason. Забирай остаток, пока ads не придёт пустым.
• Задача одна за раз: другая получит 409 task_running, номер идущей в error.task. Остановить: POST /v1/stop или DELETE /v1/tasks/{id}.
• Без подписки задача не стартует, придёт notice.
• Память с ботом общая: что ты получил в боте, через API не придёт, и наоборот.

Параметры

Другие поля и параметры, неизвестный фильтр, вариант не из списка, число вне пределов, фильтр чужой страны, limit больше 1000: ответ 400, поле в error.field. Пустое значение ("", null, []) значит «фильтра нет». Страну (gate: true в схеме) задавай первой, фильтр с countries работает только в этих странах.

Адреса

Значения фильтров

• Диапазон: 100- от 100, -500 до 500, 0-0 ровно ноль. Одно число без дефиса фильтры читают по-разному, смотри пример у фильтра.
• Разделы открываются по веткам: без parent верхние, дальше код раздела с more: true. Адрес в схеме с ?parent={country}: первым идёт код страны.
• Место пишется кодом из GET /v1/platforms/{key}/places?q=.
• В тексте лишние пробелы схлопываются, длина до max_length.

Ответ

Ответ GET /v1/tasks/{id}/ads: задача и новые объявления. Время в UTC.

{
  "task": {
    "id": "t_k3v9q2m7xw4p",
    "platform": "gumtree",
    "status": "running",
    "found": 1,
    "handed": 1,
    "limit": 200,
    "started_at": "2026-10-20T20:49:52Z",
    "ends_at": "2026-10-20T21:19:52Z"
  },
  "ads": [
    {
      "id": "2384712650",
      "title": "iPhone 13 128 GB",
      "price": 340,
      "currency": "EUR",
      "price_type": "Fixed",
      "url": "https://www.gumtree.com/ad/2384712650",
      "location": "Berlin",
      "published_at": "2026-10-20T20:46:06Z",
      "seller_name": "Marek",
      "seller_type": "Private",
      "seller_ads": 2,
      "seller_sales": 0,
      "phone": "+4915100000000",
      "whatsapp": "https://wa.me/4915100000000",
      "condition": "Used",
      "seen_by": 0
    }
  ]
}

Без подписки

POST /v1/tasks отвечает HTTP 200, task равен null, причина в notice. Подписка открывает все площадки, начатая задача доживает срок, даже если подписка кончилась.

{
  "task": null,
  "notice": {
    "code": "no_subscription",
    "message": "No subscription."
  }
}

Задача

POST /v1/tasks, GET /v1/tasks/{id}, DELETE /v1/tasks/{id} и POST /v1/stop добавляют filters, asked_at и ended_at.

Объявление

Пустых полей нет: нет телефона, нет и phone. Порядок в порции: в каком нашли.

Свои поля некоторых площадок (brand, model, year, mileage) приходят как есть.

Ошибки

Код 4xx или 5xx, field есть, когда виновато поле. no_subscription не ошибка, а 200 с notice.

{
  "error": {
    "code": "invalid_filter",
    "message": "price: must be from 0 to 100000000.",
    "field": "price"
  }
}

Заголовки: X-Request-Id в каждом ответе, X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset в ответах с ключом, Retry-After в 429 и 503. Больше 50 запросов за 10 секунд с адреса режет Cloudflare: 429 с HTML вместо JSON.

Лимиты

Скрипт

Тот же, что собирает страница площадки: создаёт задачу, забирает новое, повторяет потерянный ответ, ждёт Retry-After, выходит на done и notice.

import time

import requests

API = "https://api.fuck-api.xyz"
HEADERS = {"X-API-Key": "fp_ВАШ_КЛЮЧ"}
BODY = {
    "platform": "gumtree",
    "filters": {
        "query": "iphone 13",
        "price": [100, 500],
        "with_phone": True,
    },
    "limit": 200,
}


def show(ad):
    print(ad.get("title"), ad.get("price"), ad.get("currency", ""), ad.get("phone", "без телефона"), ad.get("url"))


def ask(method, path, **given):
    while True:
        try:
            response = requests.request(method, f"{API}{path}", headers=HEADERS, timeout=40, **given)
        except requests.RequestException:
            return None

        if response.status_code not in (429, 503):
            return response

        time.sleep(int(response.headers.get("Retry-After", 5)))


def lost(response):
    return response is None or response.status_code >= 500


def main():
    response = ask("POST", "/v1/tasks", json=BODY)

    while lost(response):
        time.sleep(5)
        response = ask("POST", "/v1/tasks", json=BODY)

    answer = response.json()

    if response.status_code != 200:
        print(answer["error"]["code"], answer["error"]["message"])
        return

    if "notice" in answer:
        print(answer["notice"]["message"])
        return

    path = f"/v1/tasks/{answer['task']['id']}/ads"
    repeat = False

    while True:
        response = ask("GET", path, params={"wait": 20, "repeat": 1} if repeat else {"wait": 20})

        if lost(response):
            repeat = True
            time.sleep(5)
            continue

        answer = response.json()

        if response.status_code != 200:
            print(answer["error"]["code"], answer["error"]["message"])
            return

        repeat = False

        for ad in answer["ads"]:
            show(ad)

        if answer["task"]["status"] == "done" and not answer["ads"]:
            print("Задача закончилась:", answer["task"].get("reason"))
            return

        time.sleep(5)


main()

Остановить задачу и посмотреть свои

import requests

API = "https://api.fuck-api.xyz"
HEADERS = {"X-API-Key": "fp_ВАШ_КЛЮЧ"}

print(requests.post(f"{API}/v1/stop", headers=HEADERS, timeout=30).json())
print(requests.get(f"{API}/v1/tasks", headers=HEADERS, timeout=30).json())
print(requests.get(f"{API}/v1/me", headers=HEADERS, timeout=30).json())

Найти код города

import requests

API = "https://api.fuck-api.xyz"
HEADERS = {"X-API-Key": "fp_ВАШ_КЛЮЧ"}
PARAMS = {
    "q": "Berlin",
}

answer = requests.get(f"{API}/v1/platforms/kleinanzeigen/places", params=PARAMS, headers=HEADERS, timeout=40).json()

if "error" in answer:
    print(answer["error"]["message"])

for place in answer.get("places", []):
    print(place["id"], place["name"], place.get("region", ""))

{"places": [{"id": "3331", "name": "Berlin", "region": "Berlin"}]}