Historypin API Documentation

API Endpoints

• Version: 7
• URL: http://www.historypin.org/en/api/

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.

Types

• type = 0 are projects / collections
• type = 1 are tours

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.

Example

/search/special:has%20comments,keyword:war/

Keys:Values

• keyword (string) - A value used to filter content based on its occurence in the title, description or short description of the content.
• tag (string) - A value representing the specific tag which an item contains.
• pin (string) - A value representing the type of the items to be retrieved. Can be one of:
  • photo
  • audio
  • video
  • text
  • collection
  • pin
  • favourite
  • tour
• license (string) - A value representing the type of License of the item. Available values are:
  • Public Domain
  • Open Government Licence
  • Creative Commons Attribution (CC-BY)
  • Creative Commons Attribution-ShareAlike (CC-BY-SA)
  • Creative Commons Attribution-NoDerivs (CC-BY-ND)
  • Creative Commons Attribution-NonCommercial (CC-BY-NC)
  • Creative Commons Attribution-NonCommercial-ShareAlike (CC-BY-NC-SA)
  • Creative Commons Attribution-NonCommercial-NoDerivs (CC-BY-NC-ND)
  • No known copyright restrictions
  • Copyright (c) all rights reserved
• special (string) - A value used for specific type of filtering
  • has comments
  • has streetview