Historypin API Documentation

API Endpoints

Before you start

Here are some things to be aware of before you start, please read them.

Projects, Collections and Tours

Historypin is a repository of user-contributed and organisation-contributed historical photographs and stories that help to tell the histories of places around the world. All of the content items on Historypin are geotagged (given a location), at least roughly, and every item has at least a rough idea of the time period when the object was created. Along with another few key fields such as title, this metadata (place, time) defines the core of the Historypin data collection, all of which is available through the Historypin API. Each Historypin metadata item, which we call a Pin, is associated with exactly one media object in the case of Image, Video and Sound pins, and consists of simple text in the case of Text pins. These Pins are grouped together into Collections, which are nested and non-exclusive, so a single Pin can have multiple parent Collections, and those Collections in turn can have multiple parent containing Collections. However, most content on Historypin is down just a couple of levels in the Collection hierarchy. Our interface also includes what we call "Classic Projects", which is how we used to allow groups of people to collaborate around themes before we standardised on a single Collection concept in the user interface. Our interface also includes Tours, which are a special kind of Collections in which pins have been put in a particular order, like a walking tour.

In our database and API, these Collection groupings are all represented as Projects with various type modifiers, which is related to historically how we used to group pins. As of the October 2015 release, all projects, collections and tours are now simply projects in the database and the API. Projects and collections are exactly the same thing and have a type = 0. Tours are quite similar to projects/collections, they have mainly some interface changes to support ordering, and they have a type = 1.


Items and Pins

Items and pins are synonyms. Each refers to a set of metadata about a single content item (with Image, Video, Sound or Text types), and to one associated media object in the case of image, video and sound pins.

Search parameters

The search parameter is used in several places and it is a bit complex. It is represented as a comma separated key:value pair list.