v0.2.0-beta

OpenAPI 3.1.0

Живая обычная органическая выдача Google

Felo API Support

MIT

Сервер

https://openapi.felo.ai

Клиентские библиотеки

Shell Curl

DataForSEO

SEO, search-engine results, keyword research, backlinks and AI visibility data.

DataForSEO Операции

post/v1/beta/dataforseo/serp/google/organic/live/regular

Живая обычная органическая выдача Google

Синхронно возвращает ранжированные результаты по ключевому слову в Google. Возвращает keyword, type, se_domain, location_code, language_code, check_url, datetime, spell, refinement_chips, item_types, items_count и items. Ответ обёрнут в конверт DataForSEO: данные в tasks[0].result, результат в tasks[0].status_code — отклонённый запрос всё равно возвращает HTTP 200.

Справочные цены

Тарификация: стоимость ответа по данным провайдера.
Справочная оценка запроса: USD 0.008.
Справочный множитель для клиента: 1.0. Не применяйте его повторно к уже рассчитанной сумме клиента.

Справочные метаданные, а не коммерческое предложение для аккаунта, гарантированная цена или лимит расходов. Кредиты ресурсов — не кредиты Felo. Итоговые списания определяются записями биллинга Felo.

Тело

application/json

Тип: array (object | null)[]
- depth
  Тип: integer | null
  
  глубина парсинга
  
  необязательное поле
  
  количество результатов в SERP
  
  значение по умолчанию: 10
  
  максимальное значение: 200
  
  С вашего аккаунта взимается плата за каждый SERP, содержащий до 10 результатов;
  Установка глубины выше 10 может привести к дополнительным списаниям, если поисковая система возвращает более 10 результатов;
  
  Стоимость можно рассчитать на странице тарифов.
- device
  Тип: string | null
  
  тип устройства
  
  необязательное поле
  
  возвращать результаты для определённого типа устройства
  
  может принимать значения:desktop, mobile
  
  значение по умолчанию: desktop
- find_targets_in
  Тип: array string[] | null
  
  типы элементов SERP для проверки на соответствие целям
  
  необязательное поле
  
  чтобы включить этот параметр, также должен быть включён stop_crawl_on_match
  
  указывает, какие типы элементов SERP следует проверять на совпадение с целями
  
  если не указано, на цели проверяются все элементы первого уровня с полями url и domain
  
  возможные значения: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitter
  
  Примечание: не может содержать те же типы элементов, что и ignore_targets_in
  
  пример:
  
  "find_targets_in": ["organic", "featured_snippet"]
  
  подробнее об этом параметре — в нашем Help Center
- group_organic_results
  Тип: boolean | null
  
  показывать связанные результаты
  
  необязательное поле
  
  если задано true, элемент related_result в ответе будет предоставлен как сниппет его родительского органического результата;
  
  если задано false, элемент related_result будет предоставлен как отдельный органический результат;
  
  значение по умолчанию: true
- ignore_targets_in
  Тип: array string[] | null
  
  типы элементов SERP, исключаемые из поиска целей
  
  необязательное поле
  
  чтобы включить этот параметр, также должен быть включён stop_crawl_on_match
  
  указывает, какие типы элементов SERP следует исключать при поиске совпадений с целями
  
  возможные значения: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitter
  
  Примечание: не может содержать те же типы элементов, что и find_targets_in
  
  пример:
  
  "ignore_targets_in": ["paid", "images"]
  
  подробнее об этом параметре — в нашем Help Center
- keyword
  Тип: string
  
  ключевое слово
  
  обязательное поле
  
  в поле keyword можно указать до 700 символов
  
  все %## будут декодированы (символ '+' декодируется в пробел)
  
  если в keyword нужен символ "%", укажите его как "%25";
  
  если в keyword нужен символ “+”, укажите его как “%2B”;
  
  если это поле содержит такие параметры, как 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', ‘cache:’, 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'site:', стоимость задачи умножается на 5
- language_code
  Тип: string
  
  код языка поисковой системы
  
  обязательное поле, если не указан language_name
  
  если используете это поле, language_name указывать не нужно
  
  список доступных языков поисковой системы с их language_code можно получить отдельным запросом к https://api.dataforseo.com/v3/serp/google/languages
  
  пример:
  
  en
- language_name
  Тип: string
  
  полное название языка поисковой системы
  
  обязательное поле, если не указан language_code
  
  если используете это поле, language_code указывать не нужно
  
  список доступных языков поисковой системы с их language_name можно получить отдельным запросом к https://api.dataforseo.com/v3/serp/google/languages
  
  пример:
  
  English
- location_code
  Тип: integer
  
  код местоположения поисковой системы
  
  обязательное поле, если не указаны location_name или location_coordinate
  
  если используете это поле, location_name или location_coordinate указывать не нужно
  
  список доступных местоположений поисковых систем с их location_code можно получить отдельным запросом к https://api.dataforseo.com/v3/serp/google/locations
  
  пример:
  
  2840
- location_coordinate
  Тип: string
  
  GPS-координаты местоположения
  
  обязательное поле, если не указаны location_name или location_code
  
  если используете это поле, location_name или location_code указывать не нужно
  
  параметр location_coordinate следует указывать в формате "latitude,longitude,radius"
  
  максимальное число десятичных знаков для "latitude" и "longitude": 7
  
  минимальное значение для "radius": 199 (мм)
  
  максимальное значение для "radius": 199999 (мм)
  
  пример:
  
  53.476225,-2.243572,200
- location_name
  Тип: string
  
  полное название местоположения поисковой системы
  
  обязательное поле, если не указаны location_code или location_coordinate
  
  если используете это поле, location_code или location_coordinate указывать не нужно
  
  список доступных местоположений поисковой системы с их location_name можно получить отдельным запросом к https://api.dataforseo.com/v3/serp/google/locations
  
  пример:
  
  London,England,United Kingdom
- match_type
  Тип: string
  
  тип соответствия цели
  
  обязательное поле, если указан stop_crawl_on_match
  
  тип соответствия для match_value
  
  возможные значения:
  
  domain – конкретный домен или поддомен
  
  with_subdomains – основной домен и поддомены
  
  wildcard – шаблон с подстановочными символами
- match_value
  Тип: string
  
  целевой домен, поддомен или значение шаблона
  
  обязательное поле, если указан stop_crawl_on_match
  
  укажите целевой домен, поддомен или значение шаблона;
  
  Примечание: домен или поддомен указывается без протокола запроса;
  
  пример: "match_value": "dataforseo.com",
  
  "match_value": "/blog/post-*"
- max_crawl_pages
  Тип: integer | null
  
  лимит обхода страниц
  
  необязательное поле
  
  количество страниц результатов поиска для обхода
  
  максимальное значение: 100
  
  Примечание: плата взимается за каждую просканированную страницу (10 органических результатов на страницу);
  
  подробнее о тарифах — на странице Pricing;
  
  Примечание#2: параметры max_crawl_pages и depth дополняют друг друга;
  
  подробнее в справочном центре
- os
  Тип: string | null
  
  операционная система устройства
  
  необязательное поле
  
  если desktop указан в поле device, выбирайте из значений: windows, macos
  
  значение по умолчанию: windows
  
  если mobile указан в поле device, выбирайте из значений: android, ios
  
  значение по умолчанию: android
- se_domain
  Тип: string | null
  
  домен поисковой системы
  
  необязательное поле
  
  мы автоматически выбираем подходящий домен поисковой системы в соответствии с указанными местоположением и языком
  
  однако в этом поле можно задать собственный домен поисковой системы
  
  пример:
  
  google.co.uk, google.com.au, google.de и т. д.
- search_param
  Тип: string | null
  
  дополнительные параметры поискового запроса
  
  необязательное поле
  
  список доступных параметров и подробности — здесь
  
  Примечание: следующие параметры поисковой системы не поддерживаются и будут автоматически сброшены, если указаны: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype.
- stop_crawl_on_match
  Тип: array (object | null)[] | null
  
  массив целей для остановки обхода необязательное поле если указано, ответ будет содержать результаты SERP до указанного match_value включительно; в этом массиве можно указать до 10 целевых значений пример: "stop_crawl_on_match":[{"match_value":"dataforseo.com","match_type":"with_subdomains"}] подробнее об этом параметре — в нашем справочном центре: https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api оплата взимается за каждый SERP, обойдённый по указанным целям
  
  match_type
  Тип: string | null
  
  тип сопоставления цели обязательное поле, если указан stop_crawl_on_match; тип сопоставления для match_value возможные значения: domain, with_subdomains, wildcard
  
  match_value
  Тип: string | null
  
  целевой домен или значение с подстановкой обязательное поле, если указан stop_crawl_on_match; укажите целевой домен или значение с подстановкой; Примечание: имя домена указывается без протокола запроса; пример: dataforseo.com
- tag
  Тип: string | null
  
  пользовательский идентификатор задачи
  
  необязательное поле
  
  ограничение — 255 символов
  
  этот параметр позволяет идентифицировать задачу и сопоставить её с результатом
  
  указанное значение tag вы найдёте в объекте data ответа
- target
  Тип: string | null
  
  целевой домен, поддомен или веб-страница для получения результатов
  
  необязательное поле
  
  домен или поддомен указывается без https:// и www.
  
  учтите, что результаты задач по target будут включать только элементы SERP, содержащие строку url;
  
  также можно использовать символ подстановки (‘*’), чтобы задать шаблон поиска в SERP и сузить результаты;
  
  примеры:
  
  example.com - возвращает результаты для домашней страницы сайта с URL, например https://example.com, https://www.example.com/ или https://example.com/;
  
  example.com* - возвращает результаты для домена, включая все его страницы;
  
  *example.com* - возвращает результаты для всего домена, включая все его страницы и поддомены;
  
  *example.com - возвращает результаты для домашней страницы независимо от поддомена, например https://en.example.com;
  
  example.com/example-page - возвращает результаты для точного URL;
  
  example.com/example-page* - возвращает результаты для всех URL домена, начинающихся с указанной строки
- target_search_mode
  Тип: string | null
  
  режим сопоставления целей
  
  необязательное поле
  
  чтобы использовать этот параметр, также должен быть включён stop_crawl_on_match
  
  определяет, как должен останавливаться обход, когда в stop_crawl_on_match указано несколько целей
  
  возможные значения: all, any
  
  all – обход останавливается только тогда, когда найдены все указанные цели
  
  any – обход останавливается при обнаружении любой одной цели
  
  значение по умолчанию: any
  
  подробнее об этом параметре — в справочном центре
- url
  Тип: string | null
  
  прямой URL поискового запроса
  
  необязательное поле
  
  можно указать прямой URL, и мы разберём его на нужные поля. Учтите, что этот способ сложнее всего обрабатывать нашему API, а также требует указать точный язык и местоположение в URL. В большинстве случаев мы не рекомендуем использовать этот способ.
  
  пример:
  
  https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
  
  Примечание: следующие параметры поисковой системы не поддерживаются и будут автоматически сброшены, если указать их в URL: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype.

Ответы

200
Тип: object | null · Response36Afe1097B20_SerpGoogleOrganicLiveRegularResponseInfo
cost
Тип: number | null Формат: double

общая стоимость задач, USD

status_code
Тип: integer | null

общий код состояния. Полный список кодов ответа можно найти здесь.

status_message
Тип: string | null

общее информационное сообщение. Полный список общих информационных сообщений можно найти здесь.

tasks
Тип: array (object | null)[] | null

массив задач

Тип: object | null · Response36Afe1097B20_SerpGoogleOrganicLiveRegularTaskInfo
cost
Тип: number | null Формат: double

общая стоимость задач, USD

data
Тип: object | null

содержит те же параметры, что вы указали в POST-запросе

propertyName
Тип: object | null
id
Тип: string | null

идентификатор задачи уникальный идентификатор задачи в нашей системе в формате UUID

path
Тип: array (string | null)[] | null

путь URL

result
Тип: array (object | null)[] | null

массив результатов

check_url
Тип: string | null

прямой URL к результатам поисковой системы
с его помощью можно убедиться, что мы предоставили точные результаты

datetime
Тип: string | null

дата и время получения результата
в формате UTC: “yyyy-mm-dd hh-mm-ss +00:00”
пример:
2019-11-15 12:57:46 +00:00

item_types
Тип: array (string | null)[] | null

типы результатов поиска, найденных в SERP
содержит типы всех результатов поиска (items), найденных в возвращённом SERP
возможные типы элементов:
answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, recipes, top_sights, scholarly_articles, popular_products, questions_and_answers, find_results_on, stocks_box, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, short_videos, refine_products, perspectives, discussions_and_forums, compare_sites, ai_overview

примечание этот массив содержит все типы результатов поиска, найденных в возвращённом SERP;
однако этот эндпоинт предоставляет данные только для типов featured_snippet, organic и paid
чтобы получить все элементы (включая функции SERP и расширенные сниппеты), найденные в возвращённом SERP, обратитесь к эндпоинту Google Organiс Advanced SERP

items
Тип: array (object | null)[] | null

элементы, входящие в элемент

page
Тип: integer | null

номер страницы результатов поиска
указывает номер страницы SERP, на которой расположен элемент

position
Тип: string | null

выравнивание элемента в SERP
может принимать следующие значения:
left, right

rectangle
Тип: object | null · Response36Afe1097B20_AiModeRectangleInfo

параметры прямоугольника
содержит декартовы координаты и размеры в пикселях сниппета результата в SERP
равно null, если calculate_rectangles в POST-запросе не установлен в true

height
Тип: number | null Формат: double

высота элемента в пикселях

width
Тип: number | null Формат: double

ширина элемента в пикселях

x
Тип: number | null Формат: double

координата по оси x координата x левого верхнего угла сниппета результата, где началом координат является левый верхний угол экрана

y
Тип: number | null Формат: double

координата по оси y координата y левого верхнего угла сниппета результата, где началом координат является левый верхний угол экрана

type
Тип: string | null

тип элемента

xpath
Тип: string | null

XPath элемента

items_count
Тип: integer | null Формат: int64

количество результатов, возвращённых в массиве items

keyword
Тип: string | null

ключевое слово, полученное в POST-массиве
ключевое слово возвращается с декодированным %## (символ '+' будет декодирован как пробел)

language_code
Тип: string | null

код языка в массиве POST

location_code
Тип: integer | null

код местоположения в массиве POST

pages_count
Тип: integer | null Формат: int64

всего получено страниц поисковых результатов
общее число полученных SERP в результате

refinement_chips
Тип: object | null · Response36Afe1097B20_RefinementChipsInfo

чипы уточнения поиска

items
Тип: array (object | null)[] | null

дочерние элементы

domain
Тип: string | null

домен в SERP

options
Тип: array (object | null)[] | null

дополнительные параметры уточнения поиска

domain
Тип: string | null

домен в SERP

title
Тип: string | null

заголовок элемента

type
Тип: string | null

тип элемента

url
Тип: string | null

URL поиска с параметрами уточнения

title
Тип: string | null

заголовок элемента

type
Тип: string | null

тип элемента

url
Тип: string | null

URL поиска с параметрами уточнения

type
Тип: string | null

тип элемента

xpath
Тип: string | null

XPath элемента

se_domain
Тип: string | null

домен поисковой системы в массиве POST

se_results_count
Тип: integer | null Формат: int64

общее количество результатов в SERP

spell
Тип: object | null · Response36Afe1097B20_SpellInfo

автокоррекция поисковой системы
если поисковая система предоставила результаты по исправленному ключевому слову, мы укажем исправленное поисковой системой ключевое слово и тип автокоррекции

keyword
Тип: string | null

ключевое слово, полученное в результате автокоррекции поисковой системы результаты будут предоставлены для исправленного ключевого слова

type
Тип: string | null

тип автокоррекции возможные значения: did_you_mean, showing_results_for, no_results_found_for, including_results_for примечание: Yahoo и Yandex поддерживают только следующий тип автокоррекции: including_results_for

type
Тип: string | null

тип элемента

result_count
Тип: integer | null Формат: int64

число элементов в массиве result

status_code
Тип: integer | null

код состояния задачи формируется DataForSEO, может находиться в диапазоне 10000-60000 Полный список кодов ответа можно найти здесь.

status_message
Тип: string | null

информационное сообщение задачи Полный список общих информационных сообщений можно найти здесь.

time
Тип: string | null

время выполнения, секунды

tasks_count
Тип: integer | null Формат: int64

число задач в массиве tasks

tasks_error
Тип: integer | null Формат: int64

число задач в массиве tasks, возвращённых с ошибкой

time
Тип: string | null

общее время выполнения, секунды

version
Тип: string | null

текущая версия API
application/json
400

Запрос не удалось обработать. Проверьте параметры запроса.
401

Требуется действительный API-ключ Felo.
402

Запрос не может быть выполнен: не выполнено требование биллинга.
403

Аккаунту не разрешено выполнять эту операцию.
429

Достигнут лимит запросов или расходов.
502

Сервис не смог выполнить запрос.
503

API или сервис биллинга временно недоступны.
504

Истекло время ожидания обработки запроса.
default

Ответ с ошибкой; сквозные ответы upstream могут использовать форматы провайдера

application/json

post/v1/beta/dataforseo/serp/google/organic/live/regular

curl https://openapi.felo.ai/v1/beta/dataforseo/serp/google/organic/live/regular \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '[
  {
    "language_code": "en",
    "location_code": 2840,
    "keyword": "albert einstein"
  }
]'

Показать схему

{
  "version": null,
  "status_code": null,
  "status_message": null,
  "time": null,
  "cost": null,
  "tasks_count": null,
  "tasks_error": null,
  "tasks": [
    {
      "id": null,
      "status_code": null,
      "status_message": null,
      "time": null,
      "cost": null,
      "result_count": null,
      "path": [
        null
      ],
      "data": null,
      "result": [
        {
          "keyword": null,
          "type": null,
          "se_domain": null,
          "location_code": null,
          "language_code": null,
          "check_url": null,
          "datetime": null,
          "spell": {
            "keyword": null,
            "type": null
          },
          "refinement_chips": {
            "type": null,
            "xpath": null,
            "items": [
              "[Max Depth Exceeded]"
            ]
          },
          "item_types": [
            null
          ],
          "se_results_count": null,
          "pages_count": null,
          "items_count": null,
          "items": [
            {
              "type": null,
              "page": null,
              "position": null,
              "xpath": null,
              "rectangle": "[Max Depth Exceeded]"
            }
          ]
        }
      ]
    }
  ]
}

Успешная операция

Нужна помощь?

По вопросам API, оплаты и аккаунта пишите в поддержку.
Общайтесь с разработчиками Felo в Discord.
Загляните в наш журнал изменений.
Нужны цены за объём или помощь с закупкой? Связаться с отделом продаж.
Создаёте на LLM? Прочитайте llms.txt.

Живая обычная органическая выдача Google

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

DataForSEO

Живая обычная органическая выдача Google

Справочные цены

Нужна помощь?