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

Оглавление

Введение

Если вы не обладаете достаточным опытом программирования и не понимаете принципов работы сетевых протоколов - просьба использовать веб-интерфейс и не трогать API. Система и документация сделаны на скорую руку и рассчитаны на более-менее опытных кодеров, которым не нужно разжёвывать элементарные вещи.

Вся архитектура серверов JustMagic построена по принципу KISS. Некоторые вещи, которые могут показаться нелогичными, неудобными или устаревшими, сделаны таким образом в угоду производительности и унификации. Например, 100млн строк, переданных в json формате, потребует относительно много памяти для распаковки. Если же эти строки передать в простом текстовом формате, разделив их символом перевода строки '\n', то любой объем можно последовательно обработать с общим расходом памяти в несколько килобайт.

Любимые ОС, язык программирования и среда разработки архитектора системы - Linux, Си (без++) и Vim, а консоль bash - это воплощение удобства и красоты дизайна. Думаю, эти вкусовые предпочтения заранее ответят на возникающие вопросы вида "А почему всё так неудобно? А где готовая объектная библиотека под основные языки? Таки шо, всё нужно самим с использованием Curl писать?" 

Общая информация

  • Ключ доступа для API можно получить в личном кабинете.
  • API доступно только для тарифов от Эцилоппа и выше.
  • Поддержка по вопросам API доступна в специальной группе Telegram, посвященной API. В группе допустимо только обсуждение API, все остальные вопросы остаются без ответов и удаляются.
  • Система в стадии тестирования, при обнаружении багов, просьба проинформировать админа по адресу support@just-magic.org. За найденные баги отсыпаем чатлов.
  • Настоятельно рекомендую подписаться на рассылку новостей API в личном кабинете, т.к. через неё будет происходить информирования об изменениях API.
  • Описание выходных данных пока не описано в документации из-за нехватки времени и их очевидности. Если что-то совсем непонятно - спрашивайте в группе telegram, и эти данные будут немедленно описаны в документации.
  • Пример кода, выполняющий простейшие операции можно скачать ТУТ. Рекомендую взять его за основу.
    • Пример должен корректно работать на версиях PHP 5.5.0, PHP 7 и выше.
    • Подразумевается консольный запуск командой './api_ex.php', либо '/usr/bin/php api_ex.php'
    • В debian, для корректного консольного запуска нужен пакет php-cli. Ну и php-curl не помешает.

Базовые принципы:

  • Все запросы отправляются на адрес https://api.just-magic.org/api_v1.php . Протокол строго https, http отвечать не будет.
  • Данные отправляются в формате JSON в POST запросе. Кодировка UTF-8.
  • Ответы возвращаются в формате json, за исключением случаев, когда был запрошен csv или xlsx файл результата.
  • HTTP код ответа должен быть 200. Если это не так, значит что-то пошло не так.
  • Все ответы имеют параметр err, который содержит короткий текстовый код ошибки и errtxt, который содержит подробное русское описание ошибки. При успешной работе err равно 0.
  • Обязательные параметры модуля постановки задач отмечены красным цветом, все остальные параметры можно игнорировать, т.к. они заполнятся значениями по умолчанию.
  • По некоторым простым параметрам, обработчика ошибок нет, при кривом значении оно будет автоматом заменено значением по умолчанию. Например, параметры search_engine или lang. Это сделано из-за нехватки времени. Чуть позже будет дописан нормальный обработчик ошибок, а пока просьба не ошибаться в параметрах. 
  • Особенности типа bool: Логическим false обладают следующие значения 0, '0', '', 'false'. Всё остальное считается true. Лучше всего юзать 0 и 1.
  • Для всех запросов должны быть обязательно переданы параметры action и apikey

 

Ограничения системы:

Ограничения на число запросов: сервер не будет обслуживать больше 2 одновременных запросов с одного ip. Просьба отправлять задачи последовательно, а не параллельно. При кривом коде, который будет бессмысленно долбить сервер нон-стопом без пауз, доступ к API будет приостановлен. Интервал проверки готовности задач, просьба делать не меньше 30 секунд.

Типы запросов.

Тип запроса передаётся через параметр action. Допустимые значения info, put_task, get_task, list_tasks.

Тип info.

Выводит общую информацию об учётной записи, типа тарифа, стоимости операций, срок действия подписки итп. Дополнительных параметров не имеет.

Тип put_task.

Команда постановки задач. Все её параметры описаны в разделе модулей постановки задач. Подробное описание параметров можно смотреть на странице веб-интерфейса. Ядро обработки постановки задач у веб-морды и данного обработчика одно и то же. Красные параметры обязательные, всё остальное ставится по умолчанию если не передано.

Единственный дополнительный параметр, не описанный в таблицах и единый для всех модулей - это justask типа bool. При его установки в true, задача валидируется, считается её стоимость, но сама задача в работу не уходит и деньги не списываются. Этот модуль нужен для расчёта стоимости и валидации задач. Или для отладки.

Как и в веб-морде, так и в АПИ, система чистит входные данные. Удаляются все кривые непечатные символы, дубликаты строк итп. Предупреждений не выводится. Давным-давно, при первых стартах системы, мы не чистили входные данные сами, а выдавали предупреждения об ошибках и их месте. Люди были недовольны и просили просто всё фиксить автоматом и отправлять в работу. С тех пор так и повелось. ))

Описание выходных данных

  • err - код ошибки, если 0, всё ок.
  • errtxt - подробное описание ошибки
  • tid - id поставленной задачи
  • size - размер задачи в условных единицах. Для некоторых модулей это строки, для некоторых слова итп
  • lim_price - цена одной единицы
  • lim_plan - стоимость задачи
  • lim_need - сколько не хватает денег. Если 0 - баланса достаточно
  • just_ask - если true, то задача не отправлена, а только валидирована и рассчитана стоимость

Тип list_tasks

Выводит общий список задач пользователя, их статусы и дополнительные данные. Задачи сортируются в обратном порядке по убыванию. Т.е. первыми идут самые свежие.

Принимает необязательные параметры limit, по умолчанию равный 10, максимально 100 и offset по умолчанию 0. Эти параметры эквиваленты аналогичным в SQL запросах. Если вы не знаете, для чего они нужны, то пользуйтесь веб-интерфейсом. ))

Тип get_task

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

  • tid - id задачи, с которой нужно работать
  • mode - режим выдачи. Допустимо info, xlsx, csv. По умолчанию info.
    • info - выдёт общие json данные о задаче, заголовки сервера:
      • Content-Type: application/json;charset=utf-8
    • xlsx - отдаёт результат в xlsx формате, заголовки сервера:
      • Content-type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
      • Content-disposition: attachment; filename=123_label.xlsx
    • csv - выдёт данные в просто текстовом формате вида csv, html или txt, в зависимости от типа задачи. Выдаваемый файл сжат gzip. Заголовки сервера:
      • Content-type: application/gzip
      • Content-disposition: attachment; filename=123_label.csv.gz
  • system - допустимо unix и win, по дефолту win. Имеет значение только для выдачи вида csv. При режиме unix выдаёт чистые данные с символом перевода строки "\n" в utf-8. Если режим выбран win, то перевод строки будет "\r\n", а в начале файла будет дописана BOM-метка юникодной кодировки.

Для режимов xlsx и csv используется не json, а бинарный формат данных, эквивалентный режиму сохранения файла в браузере.

Модули постановки задач

Модуль "Регулярки"

Тип задачи - rexp

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи rexp  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
base int Локальная база для выборки. Смотрим доступные базы в справочнике 3  
rexpa string POSIX совместимое регулярное выражение по которому будет сделана выборка кот\(ы\|ам\)  
rexpd string POSIX совместимое регулярное выражение совпадения с которым будут ИСКЛЮЧЕНЫ из выборки ^злые\s  NULL

 

Модуль "Акварель"

Тип задачи - aqua

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи aqua  
f_mail bool Необходимость отправки email, после завершения задачи true false
key string Ключевое слово, по которому будет проходить проверка купить ноутбук  
data string Проверяемый текст В нашем магазине можно купить отличный ноутбук.  
lang string Язык задачи. Возможные варианты - ru/en ru ru

 

Модуль "Акварель-генератор"

Тип задачи - aqua_gen

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи aqua_gen  
f_mail bool Необходимость отправки email, после завершения задачи true false
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". купить кота\nрозовый слон  
lang string Язык задачи. Возможные варианты - ru/en ru ru

 

Модуль "Частотность WordStat"

Тип задачи - wsfreq

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи wsfreq  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
ya_lrws int Код региона по системе кодов Яндекса. 213 NULL
device string Тип устройства пользователя согласно справочной таблице. desktop all
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". купить кота\nрозовый слон  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    
s_std bool Собирать данные вида: (купить слона) true false
s_q bool Собирать данные вида: ("купить слона") true false
s_qv bool Собирать данные вида: ("!купить !слона") true false
s_qs bool Собирать данные вида: ("[купить слона]") true false
s_qvs bool Собирать данные вида: ("[!купить !слона]") true false

  

Модуль "Подсказки WordStat"

Тип задачи - wssug

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи wssug  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
ya_lrws int Код региона по системе кодов Яндекса. 213 NULL
device string Тип устройства пользователя согласно справочной таблице. desktop all
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". купить кота\nрозовый слон  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    
page int Число собираемых страниц вордстата. (увеличивает стоимость фразы)  Допустимы целые числа от 1 до 40. При заказе 40 страниц, ценник равен 30 страницам. (скидка за объём) 40 1

 

Модуль "Текстовый анализатор"

Тип задачи - txt_anlz

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи txt_anlz  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
ya_lr int Код региона по системе кодов Яндекса. 213 213
f_type bool Соответствие по типу страниц true false
f_per bool Анализировать только пересечения true false
stop string Стоп-лист доменов. Список фраз, разделённых символом перевода строки "\n". Не более 10 доменов.

yandex.ru\nwikipedia.org\n

 yandex.ru\nwikipedia.org\n
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". Столбцы разделены символом "\t". Формат аналогичен формату xlsx файла. url1\tкупить кота\n  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    

 

Модуль "Тематический классификатор"

Тип задачи - temakl

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи temakl  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
f_gall bool Выводить 10 категорий и их условные веса. true false
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". купить кота\n  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    

Модуль "Маркеры-онлайн"

Тип задачи - mark_onl

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи mark_onl  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
ya_lr int Код региона по системе кодов Яндекса. 213 213
mode string Режим работы "hard" или "soft" soft hard
min_pwr int минимальный порог привязки. Допускается от 3 до 9. 3 3
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". Столбцы разделены символом "\t". Формат аналогичен формату xlsx файла. url1\tкупить кота\n  
data_base string База для распределения. Список фраз, разделённых символом перевода строки "\n". купить кота\nрозовый слон  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    
file_b file  Файл xlsx формата, альтернатива полю data_base. Максимум - 14мб. Если загружен файл, то поле data_base игнорируется.    

  

Модуль "Маркеры"

Тип задачи - mark

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи mark  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
base int Локальная база для выборки. Смотрим доступные базы в справочнике 3  
mode string Режим работы "hard" или "soft" soft hard
min_pwr int минимальный порог привязки. Допускается от 3 до 9. 3 3
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". Столбцы разделены символом "\t". Формат аналогичен формату xlsx файла. url1\tкупить кота\n  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    

  

Модуль "Расширение семанитики"

Тип задачи - grp_deep

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи grp_deep  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
base int Локальная база для выборки. Смотрим доступные базы в справочнике 3  
deep int Число итераций расширения. От 0 до 9. 2 1
min_pwr int минимальный порог привязки. Допускается от 3 до 9. 3 3
f_delsrc bool Удалить исходные ключи из финальной группировки true false
f_alter bool Альтернативный формат нумерации групп. false false
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". купить кота\n  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    

 

Модуль "Парсер подсказок"

Тип задачи - sug_par

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи sug_par  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
lang string Язык задачи. Возможные варианты - ru/en ru ru
ya_lr int Код региона по системе кодов Яндекса. 213 213
mode string Режим работы стандартный ("std"), валидация ("check"), отладка ("debug"). debug std
iter int Число итераций. От 1 до 3. 2 1
f_porno bool Искать порно-подсказки. false false
f_rus bool Перебор русского алфавита. false false
f_eng bool Перебор английского алфавита false false
f_num bool Перебор цифр. false false
f_space bool Добавлять пробел к базовой фразе false true
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". купить кота\n  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    

 

 

Модуль "Кластеризация семантики."

Тип задачи - grp_onl

Название параметра Тип Описание Пример По умолчанию
task string Тип задачи grp_onl  
label string Метка задачи, для удобства для озона NULL 
f_mail bool Необходимость отправки email, после завершения задачи true false
search_engine string Движок ПС, допустимо yandex или google yandex yandex
lang string Язык задачи. ru или en ru ru
ya_lr int Код региона по системе кодов Яндекса для выдачи ПС! 213 213
ya_lrws int Код региона по системе кодов Яндекса для сбора частотности. 213 NULL
google_lr string Регион гугла. Копипастим со страницы кластеризатора английское название региона до табулятора целиком, как в примере. Если будет устойчивый спрос на гугл через АПИ - открою доступ к нашей структурированной базе регионов гугла, а пока так, ибо спрос низкий, а времени мало, есть более приоритетные задачи. Saratov Oblast,Russia Moscow,Moscow,Russia
device string Тип устройства пользователя согласно справочной таблице для сбора частотности. desktop all
data string Основная задача. Список фраз, разделённых символом перевода строки "\n". купить кота\nрозовый слон  
file_t file Файл xlsx формата, альтернатива полю data. Максимум - 14мб. Если загружен файл, то поле data игнорируется.    
f_temakl bool Тематическая классификация запросов. Бесплатно, но требует сильно больше времени на выполнение задачи. false false
f_alter bool Альтернативный формат нумерации групп. false false
f_is_geo bool Определить ГЕО-зависимость запроса false false
f_is_comm bool Определение коммерческости запроса false false
s_std bool Собирать частотность вида: (купить слона) true false
s_q bool Собирать частотность вида: ("купить слона") true false
s_qv bool Собирать частотность вида: ("!купить !слона") true false
s_qs bool Собирать частотность вида: ("[купить слона]") true false
s_qvs bool Собирать частотность вида: ("[!купить !слона]") true false
domain string Домен для поиска релевнтных страниц lib.ru NULL

  Особенности модуля:

  • f_temakl может быть установлен только для языка ru, в остальных случаях он будет сброшен.
  • f_is_geo и f_is_comm может быть установлен только для языка ru и ПС yandex, в остальных случаях он будет сброшен.

Справочники

Типы устройств пользователя

Id Описание
all Все типы устрйоств
desktop
Десктопы
tablet_phone
Мобильные (Планшеты и Телефоны)
tablet
Планшеты
phone
Телефоны

Базы данных ключей

Из-за низкой популярности локальных модулей, обновление базы для нас нерентабельно, поэтому, новые локальные базы собираться не будут.

Id Год Размер Описание
3 2016 185 млн Коммерческо-информационная база широкого спектра

 

История изменений

Тут будет публиковаться история изменений и обновлений API.

23.12.2018

Запуск первой версии API.