Skip to main content

PastVu API

Deprecated

The API endpoint https://pastvu.com/api2 has been deprecated in favor of https://api.pastvu.com/api2. Please update your integrations to use the new endpoint.

info

To retrieve a photo, you need to add the contents of the file field from the API method response to the URL:

  • https://img.pastvu.com/d/ for standard size;
  • https://img.pastvu.com/a/ for original size;
  • https://img.pastvu.com/h/ for thumbnail size.

For example, file: "path/to/photo.jpg" becomes https://img.pastvu.com/d/path/to/photo.jpg for the standard-size image.

Deprecated
  • https://pastvu.com/_p/d/ for standard size;
  • https://pastvu.com/_p/a/ for original size;
  • https://pastvu.com/_p/h/ for thumbnail size.

Making requests​

Send requests to https://api.pastvu.com/api2 using GET or POST. Each request contains:

FieldRequiredTypeDescription
method✓stringAPI method name
paramsobjectmethod parameters; defaults to an empty object when omitted

For a GET request, pass params as a JSON-encoded string. Use URL encoding instead of inserting JSON into the URL manually:

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

For a POST request, send method and params in a JSON body:

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}
}'

A successful response contains the method result and a request identifier:

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

Include rid when reporting a problem: it can be used to find the request in server logs.

An API error is returned at the top level, without a result wrapper:

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

API errors, including an unknown or unavailable method, are returned with HTTP status 200 OK. Check code rather than relying on the HTTP status or the localized message alone.

The endpoint returns 400 Bad Request when a JSON string in params cannot be parsed. HTTP methods other than GET and POST return 405 Method Not Allowed with the Allow: GET, POST header.

The following methods are supported:

photo.giveForPage​

Returns the data needed to display a photo page by its cid.

ParameterMandatoryTypeDescription
cid✓intunique photo number

Query example:

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

Response example (shortened):

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

The example does not include every field of the photo object. Depending on the photo and the current user, it may also contain location, author, and region data.

FieldTypeDescription
result.photo.cidintphoto identifier
result.photo.typeintobject type: 1 for photo, 2 for painting
result.photo.filestringrelative path to the image file; prepend one of the image URLs listed above
result.photo.titlestringphoto title
result.photo.ystringdisplayed photo date
result.photo.year, result.photo.year2intfirst and last year of the object date range
result.canobjectactions available to the current user
result.forEditboolwhether editing data is included in the response
ridstringrequest identifier used for diagnostics

Errors:

CodeWhen returned
BAD_PARAMScid is missing, is not a number, or is less than 1
NO_SUCH_PHOTOthe photo does not exist or is not available to the current user

API errors are returned as JSON with a top-level code field and HTTP status 200 OK. Check code rather than relying on the HTTP status alone.

comment.giveForObj​

Returns the comment tree for a photo or news item. Top-level comments are returned in comments; replies are nested in the parent comment's comments array.

ParameterMandatoryTypeDefaultDescription
cid✓intunique object number
typestringphotoobject type: photo or news
showDelboolfalseinclude deleted comments when the authenticated user has permission to view them

Only the exact value news selects a news item. If type is omitted or has any other value, the method handles cid as a photo number. showDel has no effect on anonymous requests.

Query example:

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

Response example (shortened):

{
"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"
}

Key response fields:

FieldTypeDescription
result.cidintrequested object number
result.commentsarraytop-level comments; replies are nested recursively in comments
result.comments[].cidintunique comment number
result.comments[].userstringcomment author's login; corresponding profile data is in result.users
result.comments[].stampintcomment creation time as a Unix timestamp in milliseconds
result.comments[].txtstringcomment text as HTML; omitted for a deleted-comment placeholder
result.comments[].parentintparent comment number; included for replies
result.comments[].levelintnesting level, starting with 0 for a top-level comment
result.comments[].commentsarraydirect replies to the comment; omitted for a deleted-comment placeholder
result.comments[].delbooltrue for a deleted-comment placeholder returned with showDel
result.comments[].latestboolwhether this is the newest comment in the tree
result.countTotalinttotal number of non-deleted comments, including nested replies
result.usersobjectcomment authors keyed by login
result.latestCidintnumber of the newest comment
ridstringrequest identifier used for diagnostics

Authenticated responses also include countNew, countDel, and canReply. canModerate is true for a moderator of the object and is otherwise omitted. Individual comments can include permission and unread-status fields.

An authenticated request records the current time as the user's last comment view, resets the new-comment counter, and can clear a scheduled comment notification for the object.

With showDel: true, an eligible deleted comment is returned as a placeholder with del: true. Its txt and nested comments fields are omitted.

When no comments match, the empty response depends on authentication:

  • an anonymous response omits users and includes latestCid: 0;
  • an authenticated response includes users: {} and omits latestCid.

Errors:

CodeWhen returned
BAD_PARAMScid is missing, is 0, or cannot be converted to a number
NO_SUCH_PHOTOa photo does not exist or is not available to the current user
COMMENT_NO_OBJECTa news item does not exist or is not available to the current user

API errors are returned as JSON with a top-level code field and HTTP status 200 OK. Check code rather than relying on the HTTP status alone.

photo.giveNearestPhotos​

Returns public photos or paintings nearest to the specified point. Results are sorted from nearest to farthest, but the distance itself is not included in the response.

ParameterMandatoryTypeDefaultDescription
geo✓array [lat, lon]search point as latitude and longitude
exceptintcid of an object to exclude from the results
distanceint10000search radius in meters, from 1 to 1000000
yearintlower bound for the year field
year2intupper bound for the year field
typeint1object type: 1 for photo, 2 for painting
limitint30number of results, from 1 to 30
skipint0number of results to skip, from 0 to 999

Query example:

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

Response example (shortened):

{
"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": "..."
}

The example does not include every field that may be present in a returned object.

FieldTypeDescription
result.photosarrayobjects sorted from nearest to farthest
result.photos[].sintpublication status; the method returns objects with status 5
result.photos[].cidintobject identifier
result.photos[].filestringrelative path to the image file; prepend one of the image URLs listed above
result.photos[].titlestringobject title
result.photos[].dirstringshooting direction code
result.photos[].geoarray [lat, lon]object coordinates
result.photos[].yearintfirst year of the object date range
ridstringrequest identifier used for diagnostics

Errors:

CodeWhen returned
BAD_PARAMSgeo is missing or is not a valid latitude and longitude pair

API errors are returned as JSON with a top-level code field and HTTP status 200 OK. Check code rather than relying on the HTTP status alone.

photo.getByBounds​

Returns public photo or painting data for a map area defined by a GeoJSON Polygon or MultiPolygon. The selection rule depends on localWork:

localWorkModeResponse
falseserver-side clusteringcluster cells selected by their grid position g; single-object cells are returned in photos and groups in clusters
truedirect object lookupobjects whose coordinates are inside geometry, returned in photos; clusters is omitted

localWork is not selected automatically from z when geometry is used. Set it explicitly. The PastVu map uses server-side clustering through zoom level 16 and direct lookup from zoom level 17.

GeoJSON positions use [lon, lat]. Close each polygon ring by repeating its first position at the end. The exterior ring must follow a counterclockwise path; see RFC 7946, section 3.1.6.

ParameterMandatoryTypeDefaultDescription
geometry✓GeoJSON Polygon or MultiPolygonsearch area
z✓intzoom level, starting with 1; selects the server cluster grid in cluster mode and is echoed in the response
isPaintingboolfalsesearch paintings instead of photos
yearintlower bound for the object's year field; use together with year2
year2intupper bound for the object's year field; use together with year
localWorkboolfalseuse direct object lookup instead of server-side clusters
startAtintclient request marker echoed unchanged in the response

The year filter matches the object's first year (year) only. It does not test whether the complete year–year2 object date range overlaps the requested interval. For example, an object dated 1930–1940 is not returned for a 1936–1936 request.

The filter is applied only when both values are numbers, year is not greater than year2, and both values are within the supported range: 1826–2000 for photos or -100–1980 for paintings. The selected interval must be shorter than the complete supported range. Otherwise, the year filter is ignored.

Server-side clustering​

Use localWork: false to receive precomputed clusters for the requested z. The server selects a cluster when its grid position g is inside geometry; it does not test every object in that cluster against the polygon. Near the boundary, the response can therefore include objects outside the polygon or omit objects inside it. A selected cluster cell containing one object is returned in photos; a cell containing multiple objects is returned in clusters.

Query example:

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}

Response example (shortened):

{
"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"
}

Direct object lookup​

Use localWork: true to receive in photos every object whose coordinates are inside geometry. The server does not return clusters; the PastVu map clusters these objects in the browser.

Direct lookup has no server-side result limit or pagination, and z does not reduce the number of matched objects. Keep geometry small enough for the client to receive and process the complete response.

Query example:

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}

Response example (shortened):

{
"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"
}

Key response fields:

FieldTypeDescription
result.startAtintrequest marker copied from the input; omitted when it was not passed
result.zintrequested zoom level
result.photosarraystandalone objects in cluster mode or all matching objects in direct lookup mode
result.photos[].cidintunique object number
result.photos[].filestringrelative image path
result.photos[].dirstringshooting direction; omitted when it is not set
result.photos[].titlestringobject title
result.photos[].geoarray [lat, lon]object coordinates as latitude and longitude
result.photos[].year, result.photos[].year2intfirst and last year of the object date range
result.clustersarrayserver-side clusters; omitted in direct lookup mode
result.clusters[].cintnumber of objects in the cluster
result.clusters[].geoarray [lat, lon]cluster center coordinates
result.clusters[].pobjectobject used as the cluster poster
result.clusters[].p.geoarray [lon, lat]poster coordinates; unlike photos[].geo and cluster geo, longitude comes first
result.clusters[].garray [lon, lat]cluster grid position; included when the year filter is applied
result.clusters[].yobjectobject counts grouped by year; included when the year filter is applied
ridstringrequest identifier used for diagnostics

Errors:

CodeWhen returned
BAD_PARAMSgeometry.type is not Polygon or MultiPolygon, or z is not a number greater than or equal to 1

API errors are returned as JSON with a top-level code field and HTTP status 200 OK. Check code rather than relying on the HTTP status alone.