API и интеграция

API служит для вызова функций сайта программным способом. Это позволяет автоматизировать различные действия, доступные в веб-интерфейсе.

Для того чтобы вызвать метод, необходимо осуществить POST или GET запрос по протоколу HTTP на указанный URL:

https://socparsing.ru/api/ENTITY.METHOD?PARAMETERS&token=API_KEY
ENTITY название сущности, у которой вызывается метод. Этот параметр имеет семантическую значимость и служит для логического разделения методов
METHOD название метода из списка функций API
PARAMETERS параметры соответствующего метода API (если имеются)
API_KEY ключ доступа, который можно запросить у тех. поддержки

Ответы возращаются в формате JSON и в зависимости от успеха его выполнения имеют разный вид. В случае успешного выполнения запрос примет вид, где поле data будет содержать запрашиваемые данные или результат выполнения запроса:

{
    "status": "success",
    "data": [data]
}

В обратном случае ответ будет выглядеть так, где поле message будет содержать описание ошибки:

{
    "status": "error",
    "message": [message]
}

Ошибки будут зависеть от вызываемого метода, однако могут возникнуть и общие ошибки, которые описаны здесь.

Список методов

Пользователи
МетодОписание
users.accessTimeВозвращает время действия подписки и ее статус для владельца API_KEY
Посты
МетодОписание
posts.searchПоиск постов по заданым параметрам поиска. При отсутствии параметров поиска возращается список всех постов
posts.purchasedВозвращает список приобретенных постов владельца API_KEY. Действуют те же параметры поиска, что и для метода posts.search
posts.buyПриобретение поста для владельца API_KEY
posts.hideСкрытие поста из поиска для владельца API_KEY
posts.deleteУдаление приобретенного поста владельцем API_KEY

Общие ошибки

ОшибкаОписание
Token has wrong typeПередаваемый API-ключ имеет неверный формат данных. Ключ может содержать только буквы латинского алфавита и/или цифры
Passed token does not existПередаваемый API-ключ не был найден в базе данных
Owner of the token has been bannedВладелец API-ключа заблокирован
Owner of the token has inactive stateВладелец API-ключа имеет неактивную подписку
[Argument] must be passАргумент с названием [Argument] должен быть передан
Entity does not existЗапрашиваемая сущность не была найдена
Method does not existЗапрашиваемый метод не был найден
[Argument] with ID [id] does not existПередаваемый аргумент [Argument], имеющий ID [id] не был найден
Invalid range of argument [Argument]. It can't be less than [min] and more than [max]Передаваемый аргумент с названием [Argument] имеет недопустимое значение. Оно должно быть не меньше [min] и не больше [max]
Invalid argument type. Argument "[Argument]" must have [type] typeНеверный тип аргумента. Передаваемый аргумент [Argument] должен иметь указанный тип [type]
Database error. Try more laterОшибка базы данных
Server error. Try request more laterОшибка сервера

Метод users.accessTime

Метод возвращает дату окончания подписки и её состояние (активна/неактивна) для владельца API-ключа.


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

https://socparsing.ru/api/users.accessTime?token=4a7d1ed414474e4033ac29ccb8653d9b

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

{
     "status": "success",
     "data": {
         "state": "active",
         "access_time": "2015-07-20 00:00:00"
     }
}

Метод posts.search

Поиск постов по заданым параметрам поиска. При отсутвии параметров поиска возращается список всех постов.


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

https://socparsing.ru/api/posts.search?token=4a7d1ed414474e4033ac29ccb8653d9b&count=5

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

{
     "status": "success",
     "data": {
         "total": "706",
         "count": "5",
         "posts": [
             {"id":"2633","source":"vk","industry_id":"1","industry_name":"Отдых и туризм","photo_medium":"http://cs411416.vk.me/v411416831/6dcb/sn8zIUfKJuI.jpg","photo_small":"http://cs411416.vk.me/v411416831/6dcc/62xrBHdVY6g.jpg","sex":"1","age":"27","country_id":"1","country_name":"Россия","city_id":"60","city_name":"Казань","content":"Добрый вечер интересует тур в Египет по этому спец предложению! Один взрослый и ребенок почти 4 года !","time_post":"2015-06-27 17:12:00","time_add":"2015-06-27 23:43:53"},
             {"id":"2635","source":"vk","industry_id":"1","industry_name":"Отдых и туризм","photo_medium":"http://cs622331.vk.me/v622331730/39123/gw-V7k_ZG28.jpg","photo_small":"http://cs622331.vk.me/v622331730/39124/7x-HCYrMa9k.jpg","sex":"1","age":"0","country_id":"1","country_name":"Россия","city_id":"151","city_name":"Уфа","content":"Здравствуйте, меня интересует тур в Крым с9августа по 18","time_post":"2015-06-27 13:16:16","time_add":"2015-06-27 23:44:02"},
             {"id":"2627","source":"vk","industry_id":"4","industry_name":"Стоматология","photo_medium":"http://cs622520.vk.me/v622520177/14087/9yD8YlAHvBc.jpg","photo_small":"http://cs622520.vk.me/v622520177/14088/D8LgwN1mQIE.jpg","sex":"2","age":"23","country_id":"1","country_name":"Россия","city_id":"73","city_name":"Красноярск","content":"Друзья посоветуйте стоматологию для лечение пульпита и кариеса. Где среди хороших стоматологий дешевле?","time_post":"2015-06-27 12:48:21","time_add":"2015-06-27 23:41:54"}]}}
         ]
     }
}
Параметры запроса
ПараметрОписание
industry_id ID сферы [показать список сфер]
keywordКлючевое слово, которое должно содержаться в посте. Длина слова не может превышать 255 символов
source Идентификатор социальной сети. Может принимать 4 значения:
  • vk - ВКонтакте
  • ok - Одноклассники
  • tw - Twitter
  • fb - Facebook
country_idID страны. Список ID стран можно получить на странице API ВКонтакте
city_idID города. Список ID городов можно получить на странице API ВКонтакте
sex Идентификатор пола. Может принимать 2 значения:
  • 1 - Женщина
  • 2 - Мужчина
age_fromМинимальный возраст автора поста. Не может быть меньше 0. Если параметр задан как 0 - включает посты тех авторов, которые не указали свой возраст
age_toМаксимальный возраст автора поста. Не может быть меньше параметра age_from если оный задан, и не должен превышать 99
time_post Идентификатор периода, за который ищутся посты. Может принимать 5 значений:
  • today - сегодня
  • yesterday - вчера
  • week - последние 7 дней
  • 2weeks - последние 14 дней
  • month - последние 30 дней
countКоличество постов, необходимое получить. Не может превышать значение 200. По умолчанию 10
offsetСмещение, необходимое для выборки определенного подмножества записей. По умолчанию 0
Параметры ответа
ПараметрОписание
totalОбщее количество найденных постов. Используется для организации постраничного вывода результатов
countКоличество возращаемых постов
postsМассив постов
Возможные ошибки
ОшибкаОписание
Argument age_from can't be more than argument age_toЗначение аргумента age_from больше значения аргумента age_to
Unknown source. It must be one of vk, fb, tw, okНеверный идентификатор социальной сети. Допустимые значения: vk, ok, fb, tw
Unknown search periodНеверный идентификатор периода. Допустимые значения: today, yesterday, week, 2weeks, month
Unknown sex. It must be 1(female) or 2(male)Неверный идентификатор пола. Допустимые значения: 1 (Женщина), 2 (Мужчина)
Keyword should have length less than [length]Длина ключевого слова должна быть меньше [length] символов

Метод posts.purchased

Получение списка купленных постов для владельца API-ключа. Метод имеет такой же ответ, ошибки и те же параметры поиска, что и метод posts.search, с одной лишь исключительной особенностью - в полях возращаемого поста поле id - это ID купленного поста для владельца API-ключа, а post_id - глобальный ID поста на сайте.


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

https://socparsing.ru/api/posts.search?token=4a7d1ed414474e4033ac29ccb8653d9b&count=5

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

{
     "status": "success",
     "data": {
         "total": "706",
         "count": "5",
         "posts": [
             {"id": "20", "post_id":"2633","source":"vk","industry_id":"1","industry_name":"Отдых и туризм","photo_medium":"http://cs411416.vk.me/v411416831/6dcb/sn8zIUfKJuI.jpg","photo_small":"http://cs411416.vk.me/v411416831/6dcc/62xrBHdVY6g.jpg","sex":"1","age":"27","country_id":"1","country_name":"Россия","city_id":"60","city_name":"Казань","content":"Добрый вечер интересует тур в Египет по этому спец предложению! Один взрослый и ребенок почти 4 года !","time_post":"2015-06-27 17:12:00","time_add":"2015-06-27 23:43:53"},
             {"id": "21", "post_id":"2635","source":"vk","industry_id":"1","industry_name":"Отдых и туризм","photo_medium":"http://cs622331.vk.me/v622331730/39123/gw-V7k_ZG28.jpg","photo_small":"http://cs622331.vk.me/v622331730/39124/7x-HCYrMa9k.jpg","sex":"1","age":"0","country_id":"1","country_name":"Россия","city_id":"151","city_name":"Уфа","content":"Здравствуйте, меня интересует тур в Крым с9августа по 18","time_post":"2015-06-27 13:16:16","time_add":"2015-06-27 23:44:02"},
             {"id": "22", "post_id":"2627","source":"vk","industry_id":"4","industry_name":"Стоматология","photo_medium":"http://cs622520.vk.me/v622520177/14087/9yD8YlAHvBc.jpg","photo_small":"http://cs622520.vk.me/v622520177/14088/D8LgwN1mQIE.jpg","sex":"2","age":"23","country_id":"1","country_name":"Россия","city_id":"73","city_name":"Красноярск","content":"Друзья посоветуйте стоматологию для лечение пульпита и кариеса. Где среди хороших стоматологий дешевле?","time_post":"2015-06-27 12:48:21","time_add":"2015-06-27 23:41:54"}]}}
         ]
     }
}

Метод posts.buy

Приобретение поста для владельца API-ключа. Возвращает ссылку на профиль автора и ссылку на его пост.


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

https://socparsing.ru/api/posts.buy?token=4a7d1ed414474e4033ac29ccb8653d9b&id=2342

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

{
     "status": "success",
     "data": {
         "link_post": "https://vk.com/wall19679177_5484",
         "link_user": "https://vk.com/id19679177"
     }
}
Параметры запроса
ПараметрОписание
id Глобальный ID поста
Возможные ошибки
ОшибкаОписание
Post with ID [id] already has been purchased Пост с глобальным ID [id] был уже приобретен

Метод posts.delete

Удаление купленного поста для владельца API-ключа.


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

https://socparsing.ru/api/posts.delete?token=4a7d1ed414474e4033ac29ccb8653d9b&id=20

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

{
     "status": "success",
     "data": {
         "delete": "true"
     }
}
Параметры запроса
ПараметрОписание
id ID приобретенного поста. ID можно получить методом posts.purchased
Возможные ошибки
ОшибкаОписание
Post with PurchaseID [id] already has been purchased Приобретенный пост с ID [id] был уже куплен

Метод posts.hide

Скрытие поста из поиска для владельца API-ключа.


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

https://socparsing.ru/api/posts.hide?token=4a7d1ed414474e4033ac29ccb8653d9b&id=2164

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

{
     "status": "success",
     "data": {
         "hide": "true"
     }
}
Параметры запроса
ПараметрОписание
id Глобальный ID поста
Возможные ошибки
ОшибкаОписание
Post with ID [id] already has been hidden Пост с глобальным ID [id] уже был скрыт