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 range condition. Argument [Argument1] can't be more than argument [Argument2]Значение аргумента [Argument1] не может быть больше значения аргумента [Argument2]
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&geo[]=ct.11&geo[]=ct.25&geo[]=r.12&geo[]=r.87

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

{
     "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 сферы [показать список сфер] Обязательный параметр
wordsМассив ключевых слов, которые должны содержаться в посте
stopsМассив стоп-слов. Посты, содержащие хотя бы одно слово из массива не будут включены в результаты поиска
source Массив идентификаторов социальной сети. Каждое идентификатор может принимать только 4 значения:
  • vk - ВКонтакте
  • ok - Одноклассники
  • tw - Twitter
  • fb - Facebook
geo Массив идентификаторов стран/регионов/городов. Каждое значение должно начинаться с префикса соответствующей локации:
  • c - Страна
  • r - Регион
  • ct - Город
и заканчиваться ID локации, при этом они должны быть разделены точкой. Пример: ct.1 - Город Москва.
Список ID стран можно получить на странице API ВКонтакте
Список ID городов можно получить на странице API ВКонтакте
Список ID регионов вы можете посмотреть здесь
sex Идентификатор пола. Может принимать 2 значения:
  • 1 - Женщина
  • 2 - Мужчина
age_fromМинимальный возраст автора поста. Не может быть меньше 0. Если параметр задан как 0 - включает посты тех авторов, которые не указали свой возраст
age_toМаксимальный возраст автора поста. Не может быть меньше параметра age_from если оный задан, и не должен превышать 99
date_fromМинимальное время размещения поста Значение в формате Unix timestamp.
date_toМаксимальное время размещения поста Значение в формате Unix timestamp.
countКоличество постов, необходимое получить. Не может превышать значение 200. По умолчанию 10
offsetСмещение, необходимое для выборки определенного подмножества записей. По умолчанию 0
Параметры ответа
ПараметрОписание
totalОбщее количество найденных постов. Используется для организации постраничного вывода результатов
countКоличество возращаемых постов
postsМассив постов
Возможные ошибки
ОшибкаОписание
Unknown source. It must be one of vk, fb, tw, okНеверный идентификатор социальной сети. Допустимые значения: vk, ok, fb, tw
Unknown sex. It must be 1(female) or 2(male)Неверный идентификатор пола. Допустимые значения: 1 (Женщина), 2 (Мужчина)

Метод 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] уже был скрыт