Очередь: 0 / В работе: 1

Главная › Документация сервиса › Массовое API. Документация.

Массовое API. Документация.

При использовании API массового сбора нужно сначала создать проект, а после получить результат. Все проекты хранятся на сервисе в разделе https://word-keeper.ru/core к названиям приписывается маркер [API]. Если какие-то запросы не собрались, то лимиты по ним будут возвращены на ваш баланс.

Также обращаю ваше внимание, что сервер принимает только JSON кодированные данные методом POST (см пример, готовый скрипт в конце статьи).

Шаг 1. Создаем проект с ключевыми словами.

Создает новый проект с маркером [API] в системе на вашем аккаунте. Аналог инструмента "Проверка частотности с произв. операторами за месяц". Внимательно проверяйте фразы на правильность использования операторов wordstat. Иначе вылезет ошибка 500 и целый пакет фраз будет исключен из парсинга. За них лимиты будут возвращены. Проверить это вы сможете на странице "Статистика по лимитам"
* Формат ответа: JSON
* Метод: POST

https://word-keeper.ru/api/create_freqDiff

token - ваш токен в личном кабинете;
text - запрос [текст]: макс 1 000 фраз. Можно использовать операторы ( +, [ ], " ", ! ). Каждая фраза должна быть с новой строки.
geo - регион [число]: на данный момент поддерживается только один, например: 213.
name - название проекта [необязательно]: вы можете дать название проекту сами, либо название = 1 фраза для парсинга. Макс 250 символов
debug - режим отладки [для разрабов]: 1 - включает отладку. В этом режиме сервер возвращает ваш запрос, каким он его получил. Тем самым вы можете найти ошибки в своем запросе.

Пример правильно закодированного JSON запроса для отправки на сервер:

{"text":"шкафы купе на заказ","token":"demoapi","geo":213}

Пример JSON ответа от сервера (с комментариями):

JSON ответ закодирован:

{"code":20,"status":"ok","id":91986,"text":"Задание добавлено в очередь","words_add":1,"limit_cost":1,"limit_balance":842}

JSON раскодирован в array:
(
    [code] => 20
    [status] => ok
    [id] => 91986			// ID проекта, который был создан. Он нам нужен.
    [text] => Задание добавлено в очередь
    [words_add] => 1			// Сколько фраз было добавлено в проект
    [limit_cost] => 1			// Стоимость в лимитах
    [limit_balance] => 842		// Ваш текущий баланс лимитов
)

Пример JSON ответа от сервера в режиме отладки:

JSON ответ закодирован:

{"code":22,"status":"debug","msg":"{\"text\":\"шкафы купе на заказ\",\"token\":\"demoapi\",\"geo\":213,\"debug\":1}"}

JSON раскодирован в array:
(
    [code] => 22
    [status] => debug
    [msg] => {"text":"шкафы купе на заказ","token":"demoapi","geo":213,"debug":1}
)

Шаг 2. Получаем результат обработки

Получаем ответ от сервера. Три статуса проекта: очередь (queue), в работе (work), готов (ok). Массив данных в формате JSON.
* Формат ответа: JSON
* Метод: POST

https://word-keeper.ru/api/get_result

token - ваш токен в личном кабинете;
id - ID проекта [число]

Пример ответа (с комментариями), если проект еще в очереди / в работе:

Array
(
    [code] => 10
    [status] => queue		// Если проект еще в очереди. Если в обработке будет статус: work	
    [msg] => Проект в очереди
)

Пример ответа, если проект уже готов:

Array
(
    [results] => Array
        (
            [шкафы купе в спальню] => 11290
            [шкафы купе +в гостиную] => 2745
            [шкафы купе в !прихожую] => 24877
            ["шкафы на заказ"] => 5196
            [стенки] => 301105
            [билеты [из Питера в Москву]] => 236
            [барные стойки на кухню] => 9800
        )

    [status] => ok
    [error] => Ошибка 500! Проверьте правильность запросов 	// Появится, если в фразах ошибки (с операторами). Лимиты  за них возвращаются.
)

Удаление проектов

Удаляем проект по его ID. Максимальное количество проектов: 40. Поэтому вы можете удалять их вручную на странице "Мои проекты", либо по апи.
* Формат ответа: JSON
* Метод: POST

https://word-keeper.ru/api/remove

token - ваш токен в личном кабинете;
id - ID проекта [число]

Пример ответа (с комментариями):

Array
(
    [code] => 20
    [status] => ok
    [id] => 91986
    [text] => Проект 91986 удален
    [limit_return] =>   // Возврат лимитов происходит только в случае, если проект находится в очереди
)

Список всех проектов

Список всех ваших проектов (название и ID), которые были созданы в вашем аккаунте.
* Формат ответа: JSON
* Метод: POST

https://word-keeper.ru/api/all_cores

token - ваш токен в личном кабинете;

Пример ответа (с комментариями):

Array
(
    [cores] => Array
        (
            [91983] => шкафы купе в спальню [API]
            [91978] => шкаф купе [API]
            [91977] => "шкаф" [API]
            [91976] => "Памятники" [API]
        )

    [status] => ok
)

Пример скрипта на PHP. Готовый рабочий код

// Наши запросы для парсинга частотности. Можно подгружать из файла.
$post['text'] = 
'шкафы купе в спальню
шкафы купе +в гостиную
шкафы купе в !прихожую
"шкафы на заказ"
стенки
билеты [из Питера в Москву]
барные стойки на кухню';

// Ваш токен в личном кабинете.
$post['token'] = "demoapi";

// Регион Wordstat, цифрой. Одно значение
$post['geo'] = "213";

// Создаем проект и отправляем в обработку
$new_core = curl_top($post, 'create_freqDiff');

// Если проект успешно создан, то идем дальше
if($new_core['status'] == 'ok')
{
	// Получаем ID созданного проекта
	$post['id'] = $new_core['id'];
	
	// Зацикливаем опрос от сервиса каждые 10 сек. До 10 раз.
	for($i=0;$i<=10;$i++)
	{
		// Ждем 10 сек. Не делайте слишком часто опросы сервера. Оптимально 5-15 сек., в зависимости от фраз
		sleep(10);			

		// Запрашиваем данные по проекту
		$words = curl_top($post, 'get_result');		
		
		// Если обработка завершена, то выходим из цикла
		if($words['status'] == 'ok') 
		{
			// Удаляем проект по ID. Можно и не удалять. Но лимит 40 проектов.
			curl_top($post, 'remove');
			break;
		}
	}
    
	// Делаем, что хотим. В данном случае, просто выводим результат.
	print_r($words['results']);
}

// Функция для отправки CURL запроса методом POST
function curl_top($post, $method)
{
	$curl = curl_init();
	curl_setopt($curl, CURLOPT_URL, 'https://word-keeper.ru/api/' . $method);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
	curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);    
	curl_setopt($curl, CURLOPT_POST,1); //Будем отправлять POST запрос  
	curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($post, JSON_UNESCAPED_UNICODE));  // Кодируем в JSON наш запрос		

	$res = curl_exec($curl);
	curl_close($curl);
	
	return json_decode($res, true); //Декодируем JSON в ответе и возвращаем
}

# Примечание:
# Все созданные проекты вы можете увидеть на странице https://word-keeper.ru/core
# Не забывайте удалять проекты с помощью команды /api/remove, либо вручную на сервисе.
# Получить список всех проектов и их id можно по команде /api/all_cores
10.12.2021
Всего комментариев: 0