Инструменты данных

Как найти нужный инструмент

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

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

Что нужно	Вызов
Увидеть все инструменты или одну категорию	`GET /v1/tools`
Найти инструменты по короткому запросу, например «tiktok comments»	`POST /v1/tools/discover`
Описать целую задачу и получить план с расчётом стоимости	`POST /v1/tools/suggest`
Прочитать схему входных данных, пример и цену одного инструмента	`GET /v1/tools/{id}`

Просмотр каталога#

GET /v1/tools возвращает все доступные инструменты с ценами. Сузить список можно параметрами запроса:

category: идентификатор одной категории, например reviews или lead-generation. См. категории.
q: ключевые слова. Результаты ранжируются по релевантности, не более 100.
lang: zh или ja для локализации названий и описаний инструментов. По умолчанию — английский.

cURL

curl "https://lovelyrouter.com/v1/tools?category=reviews"

Ответ — список объектов инструментов (здесь сокращён до одного):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "description": "Reviews of a Google Maps place (by place ID or URL): text, stars, date, owner replies.",
      "price": {
        "per_call_usd": 0,
        "per_result_usd": 0.000675,
        "unit": "review",
        "label": "$0.000675 / review"
      },
      "default_results": 20,
      "max_results": 500,
      "featured": false
    }
  ]
}

Объект price содержит актуальную цену. default_results — лимит результатов, который применяется, если вы не задали max_results, а max_results — наибольший лимит, который принимает инструмент. Все поля описаны в разделе Объект инструмента.

Поиск по ключевым словам#

POST /v1/tools/discover принимает короткий запрос и возвращает лучшие совпадения с оценкой релевантности score. Названия платформ и инструментов весят больше описаний, поэтому при запросе, в котором упомянута платформа, её инструменты оказываются вверху.

cURL

curl https://lovelyrouter.com/v1/tools/discover \
  -H "content-type: application/json" \
  -d '{"query": "google maps reviews", "limit": 3}'

JSON

{
  "query": "google maps reviews",
  "count": 3,
  "results": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "default_results": 20,
      "max_results": 500,
      "score": 0.889
    },
    {
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "platform": "Google Maps",
      "category": "search",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "default_results": 10,
      "max_results": 200,
      "score": 0.717
    },
    {
      "id": "google-maps-leads",
      "name": "Google Maps leads with emails",
      "platform": "Google Maps",
      "category": "lead-generation",
      "price": { "per_call_usd": 0, "per_result_usd": 0.00075, "unit": "place", "label": "$0.00075 / place" },
      "default_results": 10,
      "max_results": 200,
      "score": 0.556
    }
  ]
}

limit по умолчанию равен 5, максимум — 40. Используйте score для упорядочивания результатов, а не как абсолютную меру: он сравнивает инструменты только в рамках одного запроса.

Планирование задачи#

Если задаче нужно больше одного инструмента или вы не знаете, какой подойдёт, опишите её обычными словами. POST /v1/tools/suggest меньше чем за секунду возвращает пошаговый план: инструмент, который нужно запустить первым, необязательный второй инструмент и близкие альтернативы — каждый с примером входных данных и оценкой стоимости.

cURL

curl https://lovelyrouter.com/v1/tools/suggest \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"task": "Find vegan restaurants in Austin and summarize what their reviews complain about"}'

Ответ в сокращённом виде:

JSON

{
  "task": "Find vegan restaurants in Austin and summarize what their reviews complain about",
  "source": "ai",
  "cached": false,
  "count": 2,
  "suggestions": [
    {
      "step": 1,
      "role": "primary",
      "match": 0.961,
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "input": {
        "searchTerms": ["coffee shop"],
        "location": "Austin, Texas, USA",
        "maxResults": 3,
        "language": "en"
      },
      "input_required": [],
      "max_results": 10,
      "est_cost_usd": 0.00313,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-places/run",
        "body": { "input": { "searchTerms": ["coffee shop"], "location": "Austin, Texas, USA", "maxResults": 3, "language": "en" }, "max_results": 10 }
      }
    },
    {
      "step": 2,
      "role": "next",
      "match": 0.875,
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" },
      "input_required": [],
      "max_results": 20,
      "est_cost_usd": 0.0135,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-reviews/run",
        "body": { "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" }, "max_results": 20 }
      }
    }
  ],
  "total_est_cost_usd": 0.01663
}

Как читать план#

role показывает роль шага: primary — инструмент, который запускается первым, next получает второй вид данных, нужный задаче (здесь — отзывы о местах, найденных на шаге 1), а alternative — близкий запасной вариант, который можно использовать вместо основного.
match — уверенность планировщика в этом шаге, от 0 до 1.
input — это пример входных данных инструмента, а не данные, составленные под вашу задачу. Замените значения своими: в примере выше "coffee shop" превращается в "vegan restaurant". В input_required перечислены поля, которые обязательно нужно заполнить. Полную схему возвращает GET /v1/tools/{id}.
est_cost_usd — максимальная стоимость шага при указанном max_results, то есть при лимите инструмента по умолчанию. Если изменить max_results, стоимость изменится пропорционально.
total_est_cost_usd — сумма шагов primary и next. Альтернативы не учитываются, потому что их запускают вместо основного шага, а не вместе с ним.
run — готовый запрос для запуска инструмента: заполните входные данные и отправьте body на path.

Пустой список suggestions означает, что ни один инструмент каталога не подходит для задачи, например «напиши стихотворение». Если планировщик недоступен, эндпоинт переключается на поиск по ключевым словам и устанавливает source в keyword. На одинаковые задачи в течение суток отвечает кеш, с cached: true.

Параметры и ограничения#

Тело запроса принимает task (обязательно, до 2000 символов), limit (число предложений, от 1 до 8, по умолчанию 5) и lang (zh или ja).

Планирование бесплатно, но с ограничением частоты запросов:

Кто вызывает	Ограничение
С API-ключом	100 запросов в минуту на ключ
Без ключа	100 запросов в минуту, общие для всех анонимных клиентов

При превышении лимита эндпоинт возвращает 429 с заголовком retry-after в секундах. Передавайте свой ключ, чтобы получить собственный лимит.

Сведения об инструменте#

Перед запуском инструмента прочитайте его схему входных данных. GET /v1/tools/{id} возвращает объект инструмента, а также input_schema (JSON Schema для input), рабочий пример example_input, ограничение времени запуска в timeout_s и готовый запрос run.

cURL

curl https://lovelyrouter.com/v1/tools/trustpilot-reviews

Ответ в сокращённом виде:

JSON

{
  "id": "trustpilot-reviews",
  "name": "Trustpilot reviews",
  "platform": "Trustpilot",
  "category": "reviews",
  "description": "Trustpilot reviews of a company by domain: stars, text, date, reply.",
  "price": {
    "per_call_usd": 0.0075,
    "per_result_usd": 0.0015,
    "unit": "review",
    "label": "$0.0015 / review + $0.0075 / call"
  },
  "default_results": 20,
  "max_results": 500,
  "featured": false,
  "input_schema": {
    "type": "object",
    "properties": {
      "companyUrls": {
        "type": "array",
        "title": "Company URLs or Domains",
        "description": "Enter Trustpilot company URLs (e.g., https://www.trustpilot.com/review/example.com) or just the domain (e.g., example.com). One per line."
      },
      "maxReviewsPerCompany": {
        "type": "integer",
        "title": "Max reviews per company (reviews)",
        "description": "Maximum number of reviews to scrape per company. Set to 0 for unlimited reviews.",
        "default": 0,
        "minimum": 0
      },
      "sort": {
        "type": "string",
        "title": "Sort Order",
        "enum": ["relevance", "recency"],
        "default": "recency"
      }
    },
    "required": ["companyUrls"]
  },
  "example_input": {
    "companyUrls": ["pipedrive.com"],
    "maxReviewsPerCompany": 20
  },
  "timeout_s": 300,
  "run": {
    "method": "POST",
    "path": "/v1/tools/trustpilot-reviews/run",
    "body": { "input": { "companyUrls": ["pipedrive.com"], "maxReviewsPerCompany": 20 }, "max_results": 20 }
  }
}

Названия полей и их смысл у разных инструментов различаются, поэтому всегда составляйте input по input_schema. Чтобы контролировать стоимость, не нужно задавать собственное поле количества инструмента (здесь maxReviewsPerCompany): max_results ограничивает запуск в любом случае. На странице инструментов показана та же схема для каждого инструмента, а после входа там же можно попробовать инструмент.

Для неизвестного или выведенного из каталога идентификатора возвращается 404.

Локализация названий и описаний#

Добавьте lang=zh или lang=ja к любому запросу к каталогу: как параметр запроса для GET или как "lang" в теле POST. Названия и описания инструментов вернутся переведёнными. Идентификаторы, цены и схемы входных данных не меняются.

cURL

curl "https://lovelyrouter.com/v1/tools/google-maps-reviews?lang=ja"

Что дальше#

Запуск инструмента

Запустите инструмент с только что составленными входными данными.

MCP-сервер

Пусть агент сам ищет, планирует и запускает.