API: Получение проектов, регионов и позиций и ключевых слов

Данный API позволяет автоматизировать получение данных ваших проектов. Получение позиций поисковых запросов, с разбивкой по дням, регионам и поисковым системам за указанный временной период.

Аутентификация

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

Api-Key: ваш_api_ключ
Content-Type: application/vnd.api+json

Шаг 1: Получение списка проектов

Метод возвращает список ваших проектов, а также связанные с ними регионы и среднюю позицию запросов.

Запрос:

curl 'https://apis.pr-cy.ru/api/v2.1.0/projects?include=keywordsSummariesStats&filter%5Bstatuses%5D=active&page%5Blimit%5D=10&page%5Boffset%5D=0' \
 -H 'Content-Type: application/vnd.api+json' \
 -H 'Api-Key: ваш_api_ключ'

Параметры:

• include=keywordsSummariesStats — добавляет статистику по ключевым словам.
• filter[statuses]=active — фильтр по активным проектам.
• page[limit] — количество проектов на странице.
• page[offset] — смещение для пагинации.

Ответ (пример):

{
  "data": [
    {
      "id": "12345",
      "type": "projects",
      "attributes": {
        "name": "example.com",
        "averagePosition": 12.3
      },
      "relationships": {
        "regions": {
          "data": [
            { "id": "678", "type": "region" }
          ]
        }
      }
    }
  ]
}

Шаг 2: Получение списка регионов для проекта

Метод возвращает список регионов, связанных с конкретным проектом.

Запрос:

curl 'https://apis.pr-cy.ru/api/v2.1.0/search-options?filter[[[[status]]]]=active&filter[[[[projectId]]]]={ID_проекта}&include=region' \
 -H 'Content-Type: application/vnd.api+json' \
 -H 'Api-Key: ваш_api_ключ'

Параметры:

• filter[projectId] — ID проекта, полученный на шаге 1.
• include=region — добавляет информацию о регионе.

Ответ (пример):

{
  "data": [
    {
      "id": "678",
      "type": "search-options",
      "attributes": {
        "regionName": "Москва"
      }
    }
  ]
}

Шаг 3: Получение данных по позициям запросов

Метод возвращает историю средних позиций ключевых запросов по выбранному региону за указанный период. Если позиция не проверялась за день, мы вернем null. Если позиция проверялась, но не была найдена: -1.

Запрос:

curl 'https://apis.pr-cy.ru/api/v3.1.0/keywords/extendedHistory/{ID_региона}?filter%5BdateFrom%5D=2025-09-25&filter%5BdateTo%5D=2025-09-26&page=1' \
 -H 'accept: application/vnd.api+json' \
 -H 'Api-Key: ваш_api_ключ'

Параметры:

• {ID_региона} — ID региона, полученный на шаге 2.
• filter[dateFrom] — дата начала периода (формат YYYY-MM-DD).
• filter[dateTo] — дата окончания периода.
• page — номер страницы для пагинации.

Ответ (пример):

{
  "data": [
    {
      "id": "98765",
      "type": "keyword",
      "attributes": {
        "keyword": "купить ноутбук",
        "averagePosition": 5.4,
        "date": "2025-09-25"
      }
    }
  ]
}

Итоговая схема работы

1. Получить проекты → взять ID проекта.
2. Получить регионы проекта → взять ID региона.
3. Запросить историю ключей по региону → получить средние позиции за нужный период.