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

Содержание

• Аутентификация
• Коды ответов
• /yandex
• /yandex/xml
• /yandex/regions
• /google
• /google/xml
• /google/regions
• /bing
• /wordstat
• /geoip

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

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

Заголовком запроса:

Authorization: Bearer ВАШ_КЛЮЧ

Параметром key:

https://jsonseo.ru/api/yandex?text=пицца&key=ВАШ_КЛЮЧ

Быстрая проверка через curl:

curl -H "Authorization: Bearer ВАШ_КЛЮЧ" "https://jsonseo.ru/api/yandex?text=пицца"

Коды ответов

/yandex

Получение поисковой выдачи из Яндекс.

Метод:

GET https://jsonseo.ru/api/yandex

Параметры запроса:

• text* (или query, q): поисковый запрос
• region (или lr): ID региона (по умолчанию: 213)
• pages: количество страниц выдачи (от 1 до 20, по умолчанию - 1)
• filter: фильтрация поиска (none, moderate, strict, по умолчанию - moderate)
• noreask: отключение автоматического исправления запроса (0 или 1, по умолчанию - 0)
• zone: доменная зона поиска (ru, com, kz, kk, by, be, uz, tr,com.tr, по умолчанию - ru)
• device: устройство (desktop, mobile, tablet). По умолчанию выдача мобильная
• break_domain: домен, на котором остановить поиск (example.com)
  Поможет сократить стоимость и время поиска, в сценариях когда нужно получить только позицию.

Стоимость запроса:

0.01₽ × количество страниц

Пример запроса:

curl "https://jsonseo.ru/api/yandex?text=купить+ноутбук&region=213&key=ВАШ_КЛЮЧ"

<?php

$params = http_build_query([
    'key' => 'ВАШ_КЛЮЧ',
    'text' => 'купить ноутбук',
    'region' => 213,
]);

$response = file_get_contents('https://jsonseo.ru/api/yandex?' . $params);
$data = json_decode($response, true);

foreach ($data['results'] as $index => $item) {
    echo ($index + 1) . '. ' . $item['url'] . PHP_EOL;
}

import requests

response = requests.get(
    'https://jsonseo.ru/api/yandex',
    params={'text': 'купить ноутбук', 'region': 213},
    headers={'Authorization': 'Bearer ВАШ_КЛЮЧ'},
)
response.raise_for_status()

for index, item in enumerate(response.json()['results'], start=1):
    print(index, item['url'])

const params = new URLSearchParams({text: 'купить ноутбук', region: 213});

const response = await fetch(`https://jsonseo.ru/api/yandex?${params}`, {
    headers: {Authorization: 'Bearer ВАШ_КЛЮЧ'},
});

const data = await response.json();
data.results.forEach((item, index) => console.log(index + 1, item.url));

Пример ответа:

{
    "pages": 1,
    "query": "купить ноутбук",
    "rawQuery": "купть ноутбук",
    "results": [
        {
            "url": "https://www.VZON.ru/category/noutbuki-15692/",
            "domain": "www.vzon.ru",
            "title": "Ноутбуки: купить ноутбук на VZON по низкой цене",
            "passage": "Покупайте ноутбуки на VZON по выгодным ценам, быстрая и бесплатная доставка...",
            "breadcrumbs": "vzon.ru›Электроника›Ноутбуки, планшеты и электронные книги"
        }
    ]
}

/yandex/xml

Получение поисковой выдачи Яндекса в формате XML.

Этот эндпоинт предназначен для интеграции в приложения и может использоваться вместо сервисов XMLRiver, XMLStock, XMLProxy, XMLSeo. Готовый URL для запросов доступен в личном кабинете.

Метод:

GET https://jsonseo.ru/api/yandex/xml

Параметры запроса:

• query*: поисковый запрос
• lr: ID региона (по умолчанию- 213)
• device: устройство (desktop, mobile, tablet). По умолчанию выдача мобильная
• domain: доменная зона поиска (ru, com, kz, kk, by, be, uz, tr,com.tr, по умолчанию - ru)
• groupby: количество позиций для сбора (кратное 10, до 200, по умолчанию 10).
• page: номер страницы (нумерация начинается с нуля, по умолчанию 0, первая страница). Смещение выдачи равно page × groupby.

Стоимость запроса:

0.01₽ × количество страниц

Пример ответа:

<?xml version="1.0" encoding="utf-8"?>
<yandexsearch version="1.0">
    <response date="20260504T120000">
        <found priority="all">128929</found>
        <found-human>128929</found-human>
        <results>
            <grouping>
                <page>0</page>
                <group id="1">
                    <doc>
                        <url>https://www.example.com/category/noutbuki/</url>
                        <domain>www.example.com</domain>
                        <title>Ноутбуки: купить ноутбук по низкой цене</title>
                        <breadcrumbs/>
                        <passages>
                            <passage>Покупайте ноутбуки по выгодным ценам, быстрая и бесплатная доставка...</passage>
                        </passages>
                        <contenttype>organic</contenttype>
                    </doc>
                </group>
            </grouping>
        </results>
    </response>
</yandexsearch>

/yandex/regions

Справочник регионов Яндекса: поиск кода региона (lr) по названию города или области. Метод бесплатный, но ключ нужен: по нему считается лимит в 30 запросов в минуту. Тот же справочник доступен на странице регионов Яндекса.

Метод:

GET https://jsonseo.ru/api/yandex/regions

Параметры запроса:

• name*: название города или области, можно частично («Казан», «Нижегородская»). Числовое значение ищется как ID региона.
• lang: язык названий в ответе (ru, en, по умолчанию - ru)

Возвращаются самые подходящие совпадения, не больше 30 за запрос: короткий запрос вроде «ново» совпадает с тысячами названий. Уточните название, если нужного региона нет в ответе.

Стоимость запроса:

Бесплатно

Пример ответа:

{
    "name": "Казань",
    "lang": "ru",
    "regions": [
        {
            "id": 43,
            "name": "Казань",
            "subname": "Республика Татарстан",
            "lat": 55.796129,
            "lon": 49.106414
        }
    ]
}

/google

Получение поисковой выдачи из Google (мобильная выдача google.com).

Метод:

GET https://jsonseo.ru/api/google

Параметры запроса:

• text* (или q): поисковый запрос
• region: ID региона Google (например, 1011969, это Москва).
  Сервер строит UULE по каноническому имени региона и подставляет gl по стране региона, если он не задан явно.
• pages: количество страниц выдачи (от 1 до 20, по умолчанию - 1)
• gl: код страны (ISO, например: ru, us, de)
• hl: язык интерфейса (например: ru, en, de)
• uule: закодированная геолокация Google (UULE)
• ll: гео координаты в формате longitude,latitude (например, 37.617633,55.755830).
  Используется только если не указаны uule и region: сервер сам закодирует координаты в UULE и привяжет выдачу к этой точке.
• nfpr: отключение автоматического исправления запроса (0 или 1, по умолчанию - 0)
• break_domain: домен, на котором остановить поиск (example.com)
  Поможет сократить стоимость и время поиска, в сценариях когда нужно получить только позицию.

Стоимость запроса:

0.01₽ × количество страниц

Пример запроса:

curl "https://jsonseo.ru/api/google?q=купить+ноутбук&region=1011969&key=ВАШ_КЛЮЧ"

<?php

$params = http_build_query([
    'key' => 'ВАШ_КЛЮЧ',
    'q' => 'купить ноутбук',
    'region' => 1011969,
]);

$response = file_get_contents('https://jsonseo.ru/api/google?' . $params);
$data = json_decode($response, true);

foreach ($data['results'] as $index => $item) {
    echo ($index + 1) . '. ' . $item['url'] . PHP_EOL;
}

import requests

response = requests.get(
    'https://jsonseo.ru/api/google',
    params={'q': 'купить ноутбук', 'region': 1011969},
    headers={'Authorization': 'Bearer ВАШ_КЛЮЧ'},
)
response.raise_for_status()

for index, item in enumerate(response.json()['results'], start=1):
    print(index, item['url'])

const params = new URLSearchParams({q: 'купить ноутбук', region: 1011969});

const response = await fetch(`https://jsonseo.ru/api/google?${params}`, {
    headers: {Authorization: 'Bearer ВАШ_КЛЮЧ'},
});

const data = await response.json();
data.results.forEach((item, index) => console.log(index + 1, item.url));

Пример ответа:

{
    "pages": 1,
    "query": "купить ноутбук",
    "rawQuery": "купть ноутбук",
    "region": "Москва, Россия",
    "url": "https://www.google.com/search?q=...",
    "results": [
        {
            "url": "https://www.example.com/category/noutbuki/",
            "domain": "www.example.com",
            "title": "Ноутбуки: купить ноутбук по низкой цене",
            "passage": "Покупайте ноутбуки по выгодным ценам, быстрая и бесплатная доставка...",
            "breadcrumbs": "example.com › Электроника › Ноутбуки"
        }
    ]
}

/google/xml

Получение поисковой выдачи Google в формате XML.

Ответ имеет ту же структуру, что и /yandex/xml, поэтому эндпоинт подходит программам, которые умеют работать с Яндекс XML (Key Collector, TopSite и другие), и может использоваться вместо сервисов XMLRiver, XMLStock, XMLProxy, XMLSeo. Готовый URL для запросов доступен в личном кабинете.

Метод:

GET https://jsonseo.ru/api/google/xml

Параметры запроса:

• query* (или text, q): поисковый запрос
• region (или loc): ID региона Google (например, 1011969, это Москва). По нему строится UULE, а gl подставляется по стране региона.
  Ради совместимости регион принимается и в параметре lr, но только числом: в XMLRiver lr означает язык результатов, а не регион.
• gl: код страны (ISO, например: ru, us, de)
• hl: язык интерфейса (например: ru, en, de)
• uule: закодированная геолокация Google (UULE), если хотите задать её сами
• ll: гео координаты в формате longitude,latitude. Используется, только если не заданы uule и region.
• nfpr: отключение автоматического исправления запроса (0 или 1, по умолчанию - 0)
• groupby: количество позиций для сбора (кратное 10, до 200, по умолчанию 10)
• page: номер страницы (нумерация начинается с нуля, по умолчанию 0). Смещение выдачи равно page × groupby.

Стоимость запроса:

0.01₽ × количество страниц

Пример ответа:

<?xml version="1.0" encoding="utf-8"?>
<yandexsearch version="1.0">
    <response date="20260504T120000">
        <found priority="all">10</found>
        <found-human>10</found-human>
        <results>
            <grouping>
                <page>0</page>
                <group id="1">
                    <doc>
                        <url>https://www.example.com/category/noutbuki/</url>
                        <domain>www.example.com</domain>
                        <title>Ноутбуки: купить ноутбук по низкой цене</title>
                        <breadcrumbs>example.com › Электроника › Ноутбуки</breadcrumbs>
                        <passages>
                            <passage>Покупайте ноутбуки по выгодным ценам, быстрая и бесплатная доставка...</passage>
                        </passages>
                        <contenttype>organic</contenttype>
                    </doc>
                </group>
            </grouping>
        </results>
    </response>
</yandexsearch>

/google/regions

Справочник регионов Google: поиск числового ID региона по названию города или страны. Вместе с ID возвращается готовый параметр uule, который можно подставить прямо в адрес выдачи Google. Метод бесплатный, но ключ нужен: по нему считается лимит в 30 запросов в минуту. Те же данные есть на страницах регионов Google и генератора UULE.

Метод:

GET https://jsonseo.ru/api/google/regions

Параметры запроса:

• name*: название города или страны на русском либо английском, можно частично («Казан», «Omsk»). Числовое значение ищется как ID региона.
• lang: язык названий в ответе (ru, en, по умолчанию - ru)

Возвращаются самые популярные совпадения, не больше 30 за запрос: короткий запрос вроде «ново» совпадает с тысячами названий. Уточните название, если нужного региона нет в ответе.

Стоимость запроса:

Бесплатно

Пример ответа:

{
    "name": "Казань",
    "lang": "ru",
    "regions": [
        {
            "id": 1012054,
            "name": "Казань",
            "subname": "Республика Татарстан, Россия",
            "type": "city",
            "type_name": "город",
            "canonical_name": "Kazan,Republic of Tatarstan,Russia",
            "uule": "w+CAIQICIiS2F6YW4sUmVwdWJsaWMgb2YgVGF0YXJzdGFuLFJ1c3NpYQ",
            "lat": 55.7878944,
            "lon": 49.1233293
        }
    ]
}

/bing

Получение поисковой выдачи из Bing (bing.com). Каждая страница содержит 10 результатов.

Метод:

GET https://jsonseo.ru/api/bing

Параметры запроса:

Локация: при нескольких параметрах Bing берёт верхний, остальные игнорирует. Без них: выдача по России (mkt=ru-RU).

• text* (или q): поисковый запрос.
• pages: страниц выдачи, 120 (по умолчанию 1).
• mkt: рынок язык-страна (ru-RU, en-US).
• cc (или gl): код страны (RU, US).
• ll: координаты latitude,longitude (55.753930,37.620795 это Красная площадь). Подпись локации придёт в поле region.
• setlang (или hl): язык интерфейса (ru, en). Регион не меняет, совместим со всеми параметрами выше.
• safesearch: off, moderate (default), strict.
• break_domain: остановить поиск на домене (поддерживает *.example.com).

Стоимость запроса:

0.01₽ × количество страниц

Пример запроса:

curl "https://jsonseo.ru/api/bing?q=пицца&ll=55.753930,37.620795&key=ВАШ_КЛЮЧ"

<?php

$params = http_build_query([
    'key' => 'ВАШ_КЛЮЧ',
    'q' => 'пицца',
    'll' => '55.753930,37.620795',
]);

$response = file_get_contents('https://jsonseo.ru/api/bing?' . $params);
$data = json_decode($response, true);

foreach ($data['results'] as $index => $item) {
    echo ($index + 1) . '. ' . $item['url'] . PHP_EOL;
}

import requests

response = requests.get(
    'https://jsonseo.ru/api/bing',
    params={'q': 'пицца', 'll': '55.753930,37.620795'},
    headers={'Authorization': 'Bearer ВАШ_КЛЮЧ'},
)
response.raise_for_status()

for index, item in enumerate(response.json()['results'], start=1):
    print(index, item['url'])

const params = new URLSearchParams({q: 'пицца', ll: '55.753930,37.620795'});

const response = await fetch(`https://jsonseo.ru/api/bing?${params}`, {
    headers: {Authorization: 'Bearer ВАШ_КЛЮЧ'},
});

const data = await response.json();
data.results.forEach((item, index) => console.log(index + 1, item.url));

Пример ответа:

{
    "pages": 1,
    "query": "пицца",
    "rawQuery": "пицца",
    "region": "Москва, Москва",
    "url": "https://www.bing.com/search?q=...",
    "results": [
        {
            "url": "https://lolo-pizza.ru/",
            "domain": "lolo-pizza.ru",
            "title": "Лоло Пицца: кушай и ржи",
            "passage": "Заказать горячую и ржачную пиццу с доставкой за 30 минут...",
            "breadcrumbs": "https://lolo-pizza.ru"
        }
    ]
}

/wordstat

Получение данных по частотности запросов из Яндекс Вордстата.

Метод:

GET https://jsonseo.ru/api/wordstat

Параметры запроса:

• text*: ключевое слово или фраза
• region: ID регионов через запятую (по умолчанию: all)
• device: типы девайсов через запятую (по умолчанию: desktop,phone,tablet)
• pages: сколько страниц популярных и похожих запросов собирать (от 1 до 20, по умолчанию - 1)

Стоимость запроса:

0.01₽ × количество страниц

Пример запроса:

curl "https://jsonseo.ru/api/wordstat?text=ремонт+айфона&region=213&key=ВАШ_КЛЮЧ"

<?php

$params = http_build_query([
    'key' => 'ВАШ_КЛЮЧ',
    'text' => 'ремонт айфона',
    'region' => 213,
]);

$response = file_get_contents('https://jsonseo.ru/api/wordstat?' . $params);
$data = json_decode($response, true);

echo 'Всего показов: ' . $data['results']['totalValue'] . PHP_EOL;

foreach ($data['results']['popular'] as $item) {
    echo $item['text'] . ': ' . $item['value'] . PHP_EOL;
}

import requests

response = requests.get(
    'https://jsonseo.ru/api/wordstat',
    params={'text': 'ремонт айфона', 'region': 213},
    headers={'Authorization': 'Bearer ВАШ_КЛЮЧ'},
)
response.raise_for_status()

results = response.json()['results']
print('Всего показов:', results['totalValue'])

for item in results['popular']:
    print(item['text'], item['value'])

const params = new URLSearchParams({text: 'ремонт айфона', region: 213});

const response = await fetch(`https://jsonseo.ru/api/wordstat?${params}`, {
    headers: {Authorization: 'Bearer ВАШ_КЛЮЧ'},
});

const {results} = await response.json();
console.log('Всего показов:', results.totalValue);
results.popular.forEach((item) => console.log(item.text, item.value));

Пример ответа:

{
    "text": "ремонт айфона",
    "pages": 5,
    "results": {
        "totalValue": 128929,
        "popular": [
            {
                "text": "ремонт айфонов",
                "value": 128927
            },
            {
                "text": "сколько ремонт айфона",
                "value": 8365
            }
        ],
        "associations": [
            {
                "text": "починить телефон",
                "value": 30546
            }
        ]
    }
}

/geoip

Определение геолокации по IP-адресу: страна, регион и координаты. ID региона совпадает с ID региона Яндекса: результат можно сразу использовать в параметре region эндпоинтов /yandex и /wordstat.

Метод:

GET https://jsonseo.ru/api/geoip

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

Метод бесплатный, но ключ обязателен: по нему считается лимит в 30 запросов в минуту.

Параметры запроса:

• ip*: IPv4-адрес, для которого нужно определить местоположение

Пример ответа:

{
    "ip": "77.88.55.242",
    "latitude": 55.753215,
    "longitude": 37.622504,
    "region": {
        "id": 213,
        "name": "Москва"
    },
    "country": {
        "id": 225,
        "name": "Россия",
        "iso_name": "RU"
    }
}