Перейти к основному содержимому

PastVu API

Устаревший адрес

API https://pastvu.com/api2 устарел. Пожалуйста, обновите ваши интеграции для использования нового адреса https://api.pastvu.com/api2.

кстати

Для получения фото, необходимо к URL добавить содержимое поля file из ответа API метода:

  • https://img.pastvu.com/d/ для стандартного размера;
  • https://img.pastvu.com/a/ для оригинального размера;
  • https://img.pastvu.com/h/ для миниатюры.

Например, из file: "path/to/photo.jpg" получится адрес изображения стандартного размера https://img.pastvu.com/d/path/to/photo.jpg.

Устаревшие адреса
  • https://pastvu.com/_p/d/ для стандартного размера;
  • https://pastvu.com/_p/a/ для оригинального размера;
  • https://pastvu.com/_p/h/ для миниатюры.

Выполнение запросов​

Отправляйте запросы на https://api.pastvu.com/api2 методом GET или POST. Каждый запрос содержит:

ПолеОбязательноеТипОписание
method✓stringназвание метода API
paramsobjectпараметры метода; если поле не указано, используется пустой объект

В запросе GET передавайте params как JSON-строку. Кодируйте параметры URL, а не вставляйте JSON в адрес вручную:

curl --get 'https://api.pastvu.com/api2' \
--data-urlencode 'method=photo.giveNearestPhotos' \
--data-urlencode 'params={"geo":[37.82,-122.469322],"limit":1}'

В запросе POST передавайте method и params в теле запроса в формате JSON:

curl --request POST 'https://api.pastvu.com/api2' \
--header 'Content-Type: application/json' \
--data '{
"method": "photo.giveNearestPhotos",
"params": {"geo": [37.82, -122.469322], "limit": 1}
}'

Успешный ответ содержит результат метода и идентификатор запроса:

{
"result": {},
"rid": "..."
}

Указывайте rid, когда сообщаете о проблеме: по нему запрос можно найти в журналах сервера.

Ошибка API возвращается на верхнем уровне, без обёртки result:

{
"type": "BadParamsError",
"code": "BAD_PARAMS",
"message": "Invalid request parameters"
}

Ошибки API, включая неизвестный или недоступный метод, возвращаются со статусом HTTP 200 OK. Проверяйте code, а не только статус HTTP или локализованное поле message.

Если JSON-строку в params не удалось разобрать, сервер возвращает 400 Bad Request. Для методов HTTP, отличных от GET и POST, сервер возвращает 405 Method Not Allowed с заголовком Allow: GET, POST.

Поддерживаются следующие методы:

photo.giveForPage​

Возвращает данные для отображения страницы снимка по идентификатору cid.

ПараметрОбязательныйТипОписание
cid✓intуникальный номер снимка

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

https://api.pastvu.com/api2?method=photo.giveForPage&params={"cid":2131190}

Сокращённый пример ответа:

{
"result": {
"photo": {
"cid": 2131190,
"file": "path/to/photo.jpg",
"title": "Надвоицкий водопад",
"y": "1925—1926",
"year": 1925,
"year2": 1926
},
"can": {},
"forEdit": false
},
"rid": "..."
}

В примере приведены не все поля объекта photo. В зависимости от снимка и текущего пользователя объект также может содержать данные о местоположении, авторе и регионах.

ПолеТипОписание
result.photo.cidintидентификатор снимка
result.photo.typeintтип объекта: 1 — фотография, 2 — картина
result.photo.filestringотносительный путь к файлу изображения; добавьте его к одному из адресов для получения изображения, указанных выше
result.photo.titlestringназвание снимка
result.photo.ystringотображаемая датировка снимка
result.photo.year, result.photo.year2intпервый и последний год датировки объекта
result.canobjectдействия, доступные текущему пользователю
result.forEditboolпризнак наличия в ответе данных для редактирования
ridstringидентификатор запроса для диагностики

Ошибки:

КодКогда возвращается
BAD_PARAMScid не указан, не является числом или меньше 1
NO_SUCH_PHOTOснимок не существует или недоступен текущему пользователю

Ошибки API возвращаются в JSON с полем code на верхнем уровне и HTTP-статусом 200 OK. Проверяйте code в ответе, а не только HTTP-статус.

comment.giveForObj​

Возвращает дерево комментариев к фотографии или новости. Комментарии верхнего уровня находятся в массиве comments, а ответы — в массиве comments родительского комментария.

ПараметрОбязательныйТипПо умолчаниюОписание
cid✓intуникальный номер объекта
typestringphotoтип объекта: photo или news
showDelboolfalseвключать удалённые комментарии, если у авторизованного пользователя есть право их просматривать

Только точное значение news выбирает новость. Если type не указан или содержит другое значение, метод обрабатывает cid как номер фотографии. Параметр showDel не влияет на анонимные запросы.

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

https://api.pastvu.com/api2?method=comment.giveForObj&params={"cid":539434}

Сокращённый пример ответа:

{
"result": {
"comments": [
{
"cid": 1324546,
"user": "user1",
"stamp": 1488382828246,
"txt": "Вероятно, снимок сделан с территории Кремля...",
"s": 5,
"type": 1,
"level": 0,
"comments": [
{
"cid": 1324559,
"user": "user2",
"stamp": 1488384195442,
"txt": "Спасибо, поправлено.",
"parent": 1324546,
"level": 1,
"s": 5,
"type": 1,
"latest": true
}
]
}
],
"countTotal": 2,
"users": {
"user1": {
"disp": "User One",
"login": "user1",
"ranks": ["mec_gold", "adviser"],
"online": false
},
"user2": {
"avatar": "/_a/h/user2.png",
"disp": "User Two",
"login": "user2",
"ranks": [],
"online": false
}
},
"latestCid": 1324559,
"cid": 539434
},
"rid": "request-id"
}

Основные поля ответа:

ПолеТипОписание
result.cidintномер запрошенного объекта
result.commentsarrayкомментарии верхнего уровня; ответы рекурсивно вложены в массивы comments
result.comments[].cidintуникальный номер комментария
result.comments[].userstringлогин автора комментария; данные профиля находятся в result.users
result.comments[].stampintвремя создания комментария в виде Unix timestamp в миллисекундах
result.comments[].txtstringтекст комментария в формате HTML; отсутствует у заглушки удалённого комментария
result.comments[].parentintномер родительского комментария; возвращается для ответов
result.comments[].levelintуровень вложенности; для комментария верхнего уровня равен 0
result.comments[].commentsarrayнепосредственные ответы на комментарий; отсутствуют у заглушки удалённого комментария
result.comments[].delboolзначение true у заглушки удалённого комментария, возвращённой с showDel
result.comments[].latestboolпризнак самого нового комментария в дереве
result.countTotalintобщее количество комментариев без удалённых, включая вложенные ответы
result.usersobjectавторы комментариев с логинами в качестве ключей
result.latestCidintномер самого нового комментария
ridstringидентификатор запроса для диагностики

Для авторизованных запросов в ответ также входят поля countNew, countDel и canReply. Поле canModerate равно true для модератора объекта, а в остальных случаях отсутствует. У отдельных комментариев могут появляться поля с правами пользователя и признаком непрочитанного комментария.

Авторизованный запрос записывает текущее время как время последнего просмотра комментариев, сбрасывает счётчик новых комментариев и может удалить запланированное уведомление о комментариях к объекту.

При showDel: true доступный удалённый комментарий возвращается как заглушка с del: true. Поля txt и вложенный массив comments у неё отсутствуют.

Если подходящих комментариев нет, состав пустого ответа зависит от авторизации:

  • в анонимном ответе нет поля users, а latestCid равен 0;
  • в авторизованном ответе есть users: {}, но нет поля latestCid.

Ошибки:

КодКогда возвращается
BAD_PARAMScid не указан, равен 0 или не преобразуется в число
NO_SUCH_PHOTOфотография не существует или недоступна текущему пользователю
COMMENT_NO_OBJECTновость не существует или недоступна текущему пользователю

Ошибки API возвращаются в JSON с полем code на верхнем уровне и HTTP-статусом 200 OK. Проверяйте code в ответе, а не только HTTP-статус.

photo.giveNearestPhotos​

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

ПараметрОбязательныйТипПо умолчаниюОписание
geo✓array [lat, lon]точка поиска: широта и долгота
exceptintcid объекта, который нужно исключить из результатов
distanceint10000радиус поиска в метрах, от 1 до 1000000
yearintнижняя граница поля year
year2intверхняя граница поля year
typeint1тип объекта: 1 — фотография, 2 — картина
limitint30количество результатов, от 1 до 30
skipint0количество пропускаемых результатов, от 0 до 999

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

https://api.pastvu.com/api2?method=photo.giveNearestPhotos&params={"geo":[37.82,-122.469322],"limit":12,"except":228481}

Сокращённый пример ответа:

{
"result": {
"photos": [
{
"s": 5,
"cid": 449459,
"file": "path/to/photo.jpg",
"title": "View of the Marin Tower of the Golden Gate Bridge under construction",
"dir": "nw",
"geo": [37.82287, -122.474985],
"year": 1934
}
]
},
"rid": "..."
}

В примере приведены не все поля, которые могут присутствовать в возвращаемом объекте.

ПолеТипОписание
result.photosarrayобъекты, отсортированные от ближайшего к самому удалённому
result.photos[].sintстатус публикации; метод возвращает объекты со статусом 5
result.photos[].cidintидентификатор объекта
result.photos[].filestringотносительный путь к файлу изображения; добавьте его к одному из адресов для получения изображения, указанных выше
result.photos[].titlestringназвание объекта
result.photos[].dirstringкод направления съёмки
result.photos[].geoarray [lat, lon]координаты объекта
result.photos[].yearintпервый год датировки объекта
ridstringидентификатор запроса для диагностики

Ошибки:

КодКогда возвращается
BAD_PARAMSgeo не указан или не является корректной парой широты и долготы

Ошибки API возвращаются в JSON с полем code на верхнем уровне и HTTP-статусом 200 OK. Проверяйте code в ответе, а не только HTTP-статус.

photo.getByBounds​

Возвращает данные опубликованных фотографий или картин для области карты, заданной GeoJSON Polygon или MultiPolygon. Правило выборки зависит от localWork:

localWorkРежимОтвет
falseкластеризация на сервереячейки кластеров, отобранные по положению g; ячейки с одним объектом возвращаются в photos, группы — в clusters
trueнепосредственный поиск объектовобъекты с координатами внутри geometry в массиве photos; поле clusters отсутствует

При использовании geometry режим localWork не выбирается автоматически по значению z. Указывайте его явно. Карта PastVu использует серверную кластеризацию до масштаба 16 включительно, а с масштаба 17 — непосредственный поиск.

Координаты GeoJSON передаются в порядке [lon, lat]. Замкните каждый контур полигона, повторив первую точку в конце. Внешний контур должен идти против часовой стрелки; см. раздел 3.1.6 RFC 7946.

ПараметрОбязательныйТипПо умолчаниюОписание
geometry✓GeoJSON (Polygon или MultiPolygon)область поиска
z✓intмасштаб от 1; выбирает сетку серверных кластеров в режиме кластеризации и возвращается в ответе
isPaintingboolfalseискать картины вместо фотографий
yearintнижняя граница поля year объекта; используется вместе с year2
year2intверхняя граница поля year объекта; используется вместе с year
localWorkboolfalseискать объекты непосредственно вместо использования серверных кластеров
startAtintклиентская метка запроса, которая без изменений возвращается в ответе

Фильтр по годам проверяет только первый год датировки объекта (year). Он не проверяет пересечение полного диапазона year–year2 объекта с запрошенным интервалом. Например, объект с датировкой 1930–1940 не попадёт в ответ на запрос за 1936–1936 годы.

Фильтр применяется, только если обе границы являются числами, year не превышает year2 и обе границы находятся в допустимом диапазоне: 1826–2000 для фотографий или -100–1980 для картин. Выбранный интервал должен быть короче полного допустимого диапазона. В остальных случаях фильтр по годам игнорируется.

Кластеризация на сервере​

Установите localWork: false, чтобы получить рассчитанные заранее кластеры для масштаба z. Сервер выбирает кластер, если его положение в сетке g находится внутри geometry, и не проверяет координаты каждого объекта в кластере. Поэтому возле границы полигона в ответ могут попасть объекты за его пределами, а объекты внутри полигона могут быть пропущены. Выбранная ячейка кластера с одним объектом возвращается в photos, с несколькими объектами — в clusters.

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

https://api.pastvu.com/api2?method=photo.getByBounds&params={"z":16,"geometry":{"type":"Polygon","coordinates":[[[-122.49,37.80],[-122.45,37.80],[-122.45,37.84],[-122.49,37.84],[-122.49,37.80]]]},"localWork":false}

Сокращённый пример ответа:

{
"result": {
"z": 16,
"photos": [
{
"cid": 1953913,
"file": "path/to/photo.jpg",
"title": "Golden Gate Bridge construction, view from Fort Baker",
"dir": "s",
"geo": [37.836174, -122.477004],
"year": 1936,
"year2": 1936
}
],
"clusters": [
{
"geo": [37.832943, -122.479384],
"c": 2,
"p": {
"cid": 561915,
"file": "path/to/poster.jpg",
"title": "Bus near Golden Gate Bridge",
"dir": "s",
"geo": [-122.479678, 37.832869],
"year": 1978,
"year2": 1978
}
}
]
},
"rid": "request-id"
}

Непосредственный поиск объектов​

Установите localWork: true, чтобы получить в photos каждый объект с координатами внутри geometry. Сервер не возвращает clusters: карта PastVu группирует объекты в браузере.

При непосредственном поиске сервер не ограничивает количество результатов и не поддерживает пагинацию, а значение z не уменьшает выборку. Задавайте geometry достаточно небольшой, чтобы клиент мог получить и обработать полный ответ.

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

https://api.pastvu.com/api2?method=photo.getByBounds&params={"z":17,"geometry":{"type":"Polygon","coordinates":[[[-122.49,37.80],[-122.45,37.80],[-122.45,37.84],[-122.49,37.84],[-122.49,37.80]]]},"year":1936,"year2":1936,"localWork":true,"startAt":1731931200000}

Сокращённый пример ответа:

{
"result": {
"startAt": 1731931200000,
"z": 17,
"photos": [
{
"cid": 1953913,
"file": "path/to/photo.jpg",
"title": "Golden Gate Bridge construction, view from Fort Baker",
"dir": "s",
"geo": [37.836174, -122.477004],
"year": 1936,
"year2": 1936
}
]
},
"rid": "request-id"
}

Основные поля ответа:

ПолеТипОписание
result.startAtintметка из запроса; отсутствует, если не была передана
result.zintзапрошенный масштаб
result.photosarrayодиночные объекты в режиме кластеров или все найденные объекты при непосредственном поиске
result.photos[].cidintуникальный номер объекта
result.photos[].filestringотносительный путь к изображению
result.photos[].dirstringнаправление съёмки; отсутствует, если не задано
result.photos[].titlestringназвание объекта
result.photos[].geoarray [lat, lon]координаты объекта: широта и долгота
result.photos[].year, result.photos[].year2intпервый и последний год датировки объекта
result.clustersarrayсерверные кластеры; отсутствует при непосредственном поиске
result.clusters[].cintколичество объектов в кластере
result.clusters[].geoarray [lat, lon]координаты центра кластера
result.clusters[].pobjectобъект, который используется как обложка кластера
result.clusters[].p.geoarray [lon, lat]координаты обложки; в отличие от photos[].geo и geo кластера, долгота идёт первой
result.clusters[].garray [lon, lat]положение кластера в сетке; возвращается при фильтрации по годам
result.clusters[].yobjectколичество объектов с группировкой по годам; возвращается при фильтрации по годам
ridstringидентификатор запроса для диагностики

Ошибки:

КодКогда возвращается
BAD_PARAMSзначение geometry.type отличается от Polygon и MultiPolygon или z не является числом от 1

Ошибки API возвращаются в JSON с полем code на верхнем уровне и HTTP-статусом 200 OK. Проверяйте code в ответе, а не только HTTP-статус.