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

Відповідь із помилкою; наскрізні відповіді апстріму можуть використовувати формати постачальника

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]"
            }
          ]
        }
      ]
    }
  ]
}

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

Жива звичайна органічна видача Google

АвтентифікаціяRequired

DataForSEO

Жива звичайна органічна видача Google

Довідкові ціни