Если вы не обладаете достаточным опытом программирования и не понимаете принципов работы сетевых протоколов - просьба использовать веб-интерфейс и не трогать API. Система и документация сделаны на скорую руку и рассчитаны на более-менее опытных кодеров, которым не нужно разжёвывать элементарные вещи.
Вся архитектура серверов JustMagic построена по принципу KISS. Некоторые вещи, которые могут показаться нелогичными, неудобными или устаревшими, сделаны таким образом в угоду производительности и унификации. Например, 100млн строк, переданных в json формате, потребует относительно много памяти для распаковки. Если же эти строки передать в простом текстовом формате, разделив их символом перевода строки '\n', то любой объем можно последовательно обработать с общим расходом памяти в несколько килобайт.
Любимые ОС, язык программирования и среда разработки архитектора системы - Linux, Си (без++) и Vim, а консоль bash - это воплощение удобства и красоты дизайна. Думаю, эти вкусовые предпочтения заранее ответят на возникающие вопросы вида "А почему всё так неудобно? А где готовая объектная библиотека под основные языки? Таки шо, всё нужно самим с использованием Curl писать?"
Ограничения на число запросов: сервер не будет обслуживать больше 2 одновременных запросов с одного ip. Просьба отправлять задачи последовательно, а не параллельно. При кривом коде, который будет бессмысленно долбить сервер нон-стопом без пауз, доступ к API будет приостановлен. Интервал проверки готовности задач, просьба делать не меньше 30 секунд.
Тип запроса передаётся через параметр action. Допустимые значения info, put_task, get_task, list_tasks.
Выводит общую информацию об учётной записи, типа тарифа, стоимости операций, срок действия подписки итп. Дополнительных параметров не имеет.
Команда постановки задач. Все её параметры описаны в разделе модулей постановки задач. Подробное описание параметров можно смотреть на странице веб-интерфейса. Ядро обработки постановки задач у веб-морды и данного обработчика одно и то же. Красные параметры обязательные, всё остальное ставится по умолчанию если не передано.
Единственный дополнительный параметр, не описанный в таблицах и единый для всех модулей - это justask типа bool. При его установки в true, задача валидируется, считается её стоимость, но сама задача в работу не уходит и деньги не списываются. Этот модуль нужен для расчёта стоимости и валидации задач. Или для отладки.
Как и в веб-морде, так и в АПИ, система чистит входные данные. Удаляются все кривые непечатные символы, дубликаты строк итп. Предупреждений не выводится. Давным-давно, при первых стартах системы, мы не чистили входные данные сами, а выдавали предупреждения об ошибках и их месте. Люди были недовольны и просили просто всё фиксить автоматом и отправлять в работу. С тех пор так и повелось. ))
Описание выходных данных
Выводит общий список задач пользователя, их статусы и дополнительные данные. Задачи сортируются в обратном порядке по убыванию. Т.е. первыми идут самые свежие.
Принимает необязательные параметры limit, по умолчанию равный 10, максимально 100 и offset по умолчанию 0. Эти параметры эквиваленты аналогичным в SQL запросах. Если вы не знаете, для чего они нужны, то пользуйтесь веб-интерфейсом. ))
Служит для получения информации о конкретной задаче и выгрузке результата. Описание доп. параметров:
Для режимов 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 |
| search_engine | string | Движок ПС, допустимо yandex или google | yandex | yandex |
Тип задачи - aqua_gen
| Название параметра | Тип | Описание | Пример | По умолчанию |
| task | string | Тип задачи | aqua_gen | |
| f_mail | bool | Необходимость отправки email, после завершения задачи | true | false |
| data | string | Основная задача. Список фраз, разделённых символом перевода строки "\n". | купить кота\nрозовый слон | |
| lang | string | Язык задачи. Возможные варианты - ru/en | ru | ru |
| search_engine | string | Движок ПС, допустимо yandex или google | yandex | yandex |
Тип задачи - 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 |
Тип задачи - 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 |
| search_engine | string | Движок ПС, допустимо yandex или google | yandex | yandex |
| ya_lr | int | Код региона по системе кодов Яндекса. | 213 | 213 |
| google_lr | string | Регион гугла. Копипастим со страницы кластеризатора английское название региона до табулятора целиком, как в примере. Если будет устойчивый спрос на гугл через АПИ - открою доступ к нашей структурированной базе регионов гугла, а пока так, ибо спрос низкий, а времени мало, есть более приоритетные задачи. | Saratov Oblast,Russia | Moscow,Moscow,Russia |
| f_type | bool | Соответствие по типу страниц | true | false |
| f_per | bool | Анализировать только пересечения | true | false |
| src_ua | int | User-agent для анализируемой страницы. Возможные варианты смотрим на странице ТА. | 2 | 1 |
| 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 |
Особенности модуля:
| Id | Описание |
| all | Все типы устрйоств |
| desktop |
Десктопы |
| tablet_phone |
Мобильные (Планшеты и Телефоны) |
| tablet |
Планшеты |
| phone |
Телефоны |
Из-за низкой популярности локальных модулей, обновление базы для нас нерентабельно, поэтому, новые локальные базы собираться не будут.
| Id | Год | Размер | Описание |
| 3 | 2016 | 185 млн | Коммерческо-информационная база широкого спектра |
Тут будет публиковаться история изменений и обновлений API.
В ТА, акварели и аквагенераторе добавлена поддержка выбора ПС.
Запуск первой версии API.