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 |
params | object | параметры метода; если поле не указано, используется пустой объект |
В запросе 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¶ms={"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.cid | int | идентификатор снимка |
result.photo.type | int | тип объекта: 1 — фотография, 2 — картина |
result.photo.file | string | относительный путь к файлу изображения; добавьте его к одному из адресов для получения изображения, указанных выше |
result.photo.title | string | название снимка |
result.photo.y | string | отображаемая датировка снимка |
result.photo.year, result.photo.year2 | int | первый и последний год датировки объекта |
result.can | object | действия, доступные текущему пользователю |
result.forEdit | bool | признак наличия в ответе данных для редактирования |
rid | string | идентификатор запроса для диагностики |
Ошибки:
| Код | Когда возвращается |
|---|---|
BAD_PARAMS | cid не указан, не является числом или меньше 1 |
NO_SUCH_PHOTO | снимок не существует или недоступен текущему пользователю |
Ошибки API возвращаются в JSON с полем code на верхнем уровне и HTTP-статусом 200 OK. Проверяйте code в ответе, а не только HTTP-статус.
comment.giveForObj
Возвращает дерево комментариев к фотографии или новости. Комментарии верхнего уровня находятся в массиве comments, а ответы — в массиве comments родительского комментария.
| Параметр | Обязательный | Тип | По умолчанию | Описание |
|---|---|---|---|---|
| cid | ✓ | int | уникальный номер объекта | |
| type | string | photo | тип объекта: photo или news | |
| showDel | bool | false | включать удалённые комментарии, если у авторизованного пользователя есть право их просматривать |
Только точное значение news выбирает новость. Если type не указан или содержит другое значение, метод обрабатывает cid как номер фотографии. Параметр showDel не влияет на анонимные запросы.
Пример запроса:
https://api.pastvu.com/api2?method=comment.giveForObj¶ms={"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.cid | int | номер запрошенного объекта |
result.comments | array | комментарии верхнего уровня; ответы рекурсивно вложены в массивы comments |
result.comments[].cid | int | уникальный номер комментария |
result.comments[].user | string | логин автора комментария; данные профиля находятся в result.users |
result.comments[].stamp | int | время создания комментария в виде Unix timestamp в миллисекундах |
result.comments[].txt | string | текст комментария в формате HTML; отсутствует у заглушки удалённого комментария |
result.comments[].parent | int | номер родительского комментария; возвращается для ответов |
result.comments[].level | int | уровень вложенности; для комментария верхнего уровня равен 0 |
result.comments[].comments | array | непосредственные ответы на комментарий; отсутствуют у заглушки удалённого комментария |
result.comments[].del | bool | значение true у заглушки удалённого комментария, возвращённой с showDel |
result.comments[].latest | bool | признак самого нового комментария в дереве |
result.countTotal | int | общее количество комментариев без удалённых, включая вложенные ответы |
result.users | object | авторы комментариев с логинами в качестве ключей |
result.latestCid | int | номер самого нового комментария |
rid | string | идентификатор запроса для диагностики |
Для авторизованных запросов в ответ также входят поля countNew, countDel и canReply. Поле canModerate равно true для модератора объекта, а в остальных случаях отсутствует. У отдельных комментариев могут появляться поля с правами пользователя и признаком непрочитанного комментария.
Авторизованный запрос записывает текущее время как время последнего просмотра комментариев, сбрасывает счётчик новых комментариев и может удалить запланированное уведомление о комментариях к объекту.
При showDel: true доступный удалённый комментарий возвращается как заглушка с del: true. Поля txt и вложенный массив comments у неё отсутствуют.
Если подходящих комментариев нет, состав пустого ответа зависит от авторизации:
- в анонимном ответе нет поля
users, аlatestCidравен0; - в авторизованном ответе есть
users: {}, но нет поляlatestCid.
Ошибки:
| Код | Когда возвращается |
|---|---|
BAD_PARAMS | cid не указан, равен 0 или не преобразуется в число |
NO_SUCH_PHOTO | фотография не существует или недоступна текущему пользователю |
COMMENT_NO_OBJECT | новость не существует или недоступна текущему пользователю |
Ошибки API возвращаются в JSON с полем code на верхнем уровне и HTTP-статусом 200 OK. Проверяйте code в ответе, а не только HTTP-статус.
photo.giveNearestPhotos
Возвращает опубликованные фотографии или картины, ближайшие к заданной точке. Результаты отсортированы от ближайшего к самому удалённому, но само расстояние в ответ не включено.
| Параметр | Обязательный | Тип | По умолчанию | Описание |
|---|---|---|---|---|
| geo | ✓ | array [lat, lon] | точка поиска: широта и долгота | |
| except | int | cid объекта, который нужно исключить из результатов | ||
| distance | int | 10000 | радиус поиска в метрах, от 1 до 1000000 | |
| year | int | нижняя граница поля year | ||
| year2 | int | верхняя граница поля year | ||
| type | int | 1 | тип объекта: 1 — фотография, 2 — картина | |
| limit | int | 30 | количество результатов, от 1 до 30 | |
| skip | int | 0 | количество пропускаемых результатов, от 0 до 999 |
Пример запроса:
https://api.pastvu.com/api2?method=photo.giveNearestPhotos¶ms={"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.photos | array | объекты, отсортированные от ближайшего к самому удалённому |
result.photos[].s | int | статус публикации; метод возвращает объекты со статусом 5 |
result.photos[].cid | int | идентификатор объекта |
result.photos[].file | string | относительный путь к файлу изображения; добавьте его к одному из адресов для получения изображения, указанных выше |
result.photos[].title | string | название объекта |
result.photos[].dir | string | код направления съёмки |
result.photos[].geo | array [lat, lon] | координаты объекта |
result.photos[].year | int | первый год датировки объекта |
rid | string | идентификатор запроса для диагностики |
Ошибки:
| Код | Когда возвращается |
|---|---|
BAD_PARAMS | geo не указан или не является корректной парой широты и долготы |
Ошибки 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; выбирает сетку серверных кластеров в режиме кластеризации и возвращается в ответе | |
| isPainting | bool | false | искать картины вместо фотографий | |
| year | int | нижняя граница поля year объекта; используется вместе с year2 | ||
| year2 | int | верхняя граница поля year объекта; используется вместе с year | ||
| localWork | bool | false | искать объекты непосредственно вместо использования серверных кластеров | |
| startAt | int | клиентская метка запроса, которая без изменений возвращается в ответе |
Фильтр по годам проверяет только первый год датировки объекта (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¶ms={"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¶ms={"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.startAt | int | метка из запроса; отсутствует, если не была передана |
result.z | int | запрошенный масштаб |
result.photos | array | одиночные объекты в режиме кластеров или все найденные объекты при непосредственном поиске |
result.photos[].cid | int | уникальный номер объекта |
result.photos[].file | string | относительный путь к изображению |
result.photos[].dir | string | направление съёмки; отсутствует, если не задано |
result.photos[].title | string | название объекта |
result.photos[].geo | array [lat, lon] | координаты объекта: широта и долгота |
result.photos[].year, result.photos[].year2 | int | первый и последний год датировки объекта |
result.clusters | array | серверные кластеры; отсутствует при непосредственном поиске |
result.clusters[].c | int | количество объектов в кластере |
result.clusters[].geo | array [lat, lon] | координаты центра кластера |
result.clusters[].p | object | объект, который используется как обложка кластера |
result.clusters[].p.geo | array [lon, lat] | координаты обложки; в отличие от photos[].geo и geo кластера, долгота идёт первой |
result.clusters[].g | array [lon, lat] | положение кластера в сетке; возвращается при фильтрации по годам |
result.clusters[].y | object | количество объектов с группировкой по годам; возвращается при фильтрации по годам |
rid | string | идентификатор запроса для диагностики |
Ошибки:
| Код | Когда возвращается |
|---|---|
BAD_PARAMS | значение geometry.type отличается от Polygon и MultiPolygon или z не является числом от 1 |
Ошибки API возвращаются в JSON с полем code на верхнем уровне и HTTP-статусом 200 OK. Проверяйте code в ответе, а не только HTTP-статус.