Time Travel APIs
Last updated: April 23, 2015


Abstract
This document describes the APIs that are associated with the Time Travel service.
Table of Contents
1. URI that redirects to a Memento
2. URI that provides access to a JSON description of a Memento
3. TimeMap for access to version history, as per the Memento protocol
    3.1. "Do It Yourself" TimeMap - Fast Response, the Client does the Heavy Lifting
    3.2. "We Do It" TimeMap - Slow Response, the Time Travel service does the Heavy Lifting
4. TimeGate for datetime negotiation, as per the Memento protocol
5. Time Travel Prediction Service - List of DIY TimeMap and TimeGate URIs of a Memento
6. Time Travel Archive Registry
1. URI that redirects to a Memento
The Time Travel service provides an easy way to be redirected to a Memento for a given resource with an archival/version datetime that is close to a desired one.
Request
Simply append the desired datetime and the URI of the resource to the baseURL of this redirection service.

http://timetravel.mementoweb.org/memento/​YYYY<MM|DD|HH|MM|SS>​/​URI
Request Example
Using https://github.com/mementoweb/SiteStory as an example URI, these are valid requests:

http://timetravel.mementoweb.org/memento/2013/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/201301/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/20130115/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/2013011510/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/201301151020/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/20130115102033/https://github.com/mementoweb/SiteStory
Response
A redirect (HTTP "302 Found" status code) to the Memento for the requested resource that is temporally closest to the desired datetime, irrespective of the memento_compliant archive or versioning system it resides in.
Response Example
HTTP/1.1 302 Found Date: Fri, 31 Oct 2014 20:44:44 GMT Content-Type: text/plain; charset=iso-8859-1 Content-Length: 0 Location: http://en.wikipedia.org/w/index.php?title=Web_archiving&oldid=526371727
Using the redirecting URI for linking in HTML
When using the redirecting URI in a link in HTML, please consider annotating the link with HTML5 extension attributes that make the link robust over time; see Robust Links for further information. Add the following attributes:
These attributes make sure that this essential information about the link does not vanish and they can be used by memento_compliant tools, such as Memento for Chrome​, to navigate towards the original URI or to other prior versions of it.
Example
Using the redirecting URI http://timetravel.mementoweb.org/memento/20130115102033/http://en.wikipedia.org/wiki/web_archiving as an example URI, this what the HTML link would look like:
<a href="http://timetravel.mementoweb.org/memento/20130115102033/http://en.wikipedia.org/wiki/web_archiving" data-originalurl="http://en.wikipedia.org/wiki/web_archiving" data-versiondate="2013-01-15T10:20:33Z">some text here</a>
2. URI that provides access to a JSON description of a Memento
The Time Travel service provides access to a JSON document that details a Memento for a given resource with an archival/version datetime that is close to a desired one.
Request
Simply append the desired datetime and the URI of the resource to the baseURL of this JSON service.

http://timetravel.mementoweb.org/api/json/​YYYY<MM|DD|HH|MM|SS>​/​URI
Request Example
Using http://cnn.com as an example URI, these are valid requests:

http://timetravel.mementoweb.org/api/json/2013/http://cnn.com
http://timetravel.mementoweb.org/api/json/201301/http://cnn.com
http://timetravel.mementoweb.org/api/json/20130115/http://cnn.com
http://timetravel.mementoweb.org/api/json/2013011510/http://cnn.com
http://timetravel.mementoweb.org/api/json/201301151020/http://cnn.com
http://timetravel.mementoweb.org/api/json/20130115102033/http://cnn.com
Response
A JSON document that lists the Memento for the requested resource that is temporally closest (closest) to the desired datetime, irrespective of the memento_compliant archive or versioning system it resides in. It also lists, when possible, the Mementos that are adjacent to the closest one (prev, next) as well as very first and most recent Mementos (first, last). For each Memento, it lists the archival/version datetime (​datetime​). For each of these Mementos, the response may list duplicates, i.e. Mementos with the same datetime but different URIs. In addition the document lists the URI for which the JSON was requested (​original_uri​), as well as the URI of the TimeGate (​timegate_uri​) and the TimeMap (​timemap_uri​) provided by the Time Travel service.
Response Example
Using the request http://timetravel.mementoweb.org/api/json/20130115102033/http://cnn.com as an example, this would be a sample JSON response that includes duplicates for the closest and most recent Mementos:
{ "original_uri": "http://www.cnn.com/", "mementos": { "last": { "datetime": "2014-10-07T18:32:00Z", "uri": [ "http://web.archive.org/web/20141007183200/http://www.cnn.com/", "http://wayback.vefsafn.is/wayback/20141007183200/http://www.cnn.com/" ] }, "next": { "datetime": "2013-01-15T11:01:01Z", "uri": [ "http://web.archive.org/web/20130115110101/http://www.cnn.com/" ] }, "closest": { "datetime": "2013-01-15T09:46:43Z", "uri": [ "http://web.archive.org/web/20130115094643/http://www.cnn.com/", "http://archive.today/aaqIY" ] }, "first": { "datetime": "2000-06-20T18:02:59Z", "uri": [ "http://arquivo.pt/wayback/wayback/20000620180259/http://cnn.com/" ] }, "prev": { "datetime": "2013-01-15T08:17:14Z", "uri": [ "http://web.archive.org/web/20130115081714/http://www.cnn.com/" ] } }, "timegate_uri": "http://timetravel.mementoweb.org/timegate/http://www.cnn.com/", "timemap_uri": { "link_format": "http://timetravel.mementoweb.org/timemap/link/http://cnn.com", "json_format": "http://timetravel.mementoweb.org/timemap/json/http://cnn.com" } }
3. TimeMap for access to version history
The Time Travel service provides ways to access a TimeMap for a resource with a given URI. A TimeMap, as defined in the Memento protocol (RFC 7089), provides an overview of all Mementos (and their archival/version datetimes) known to the responding server. A brief description of TimeMaps is available in the Introduction to Memento​.

As the Time Travel service covers many web archives and versioning systems, a TimeMap for any given resource can list Mementos available in multiple remote servers. Information about access to TimeMaps for individual systems is available in the Memento Depot. This document details access to TimeMaps that the Time Travel service aggregates across web archives and content management systems.

The Time Travel service provides access to two types of TimeMaps:
Each type of TimeMap is available in two serialization formats:
3.1. "Do It Yourself" TimeMap for access to version history
The DIY TimeMap service does not provide information about actual Mementos. Rather, it returns a list of TimeMap URIs that may be exposed by archives. The response is based on a machine learning approach that tries to determine which archives hold Mementos for which URIs. As such, some listed TimeMap URIs may actually not really exist and TimeMap URIs may exist that are not listed. The machine learning approach leans towards avoiding the latter. Responses should be fast but the client is left with the task of collecting information about actual Mementos across archives by dereferencing the listed TimeMap URIs.

The response, in both serialization formats, is delivered as an Index TimeMap. Index TimeMaps for the application/link-format serialization are described in Section 5.1.1 of RFC 7089. Index TimeMaps for the application/json serialization are described in JSON TimeMaps​. In both serialization formats, information is provided that may be helpful to a client to decide whether or not to dereference a potential TimeMap URI:
Request
Simply append the format indicator (link or json) and the URI of the resource to the baseURL of the DIY TimeMap service.

http://timetravel.mementoweb.org/timemap/​format​/​URI
Request Example
Using http://www.lamonitor.com as an example URI, the DIY TimeMap formatted according to the application/link-format MIME type is requested as follows:

http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com

whereas the TimeMap formatted according to the application/json MIME type is requested as follows:

http://timetravel.mementoweb.org/timemap/json/http://www.lamonitor.com
Response
An Index TimeMap formatted according to the requested MIME type (​application/link-format or application/json​) that lists potential TimeMap URIs in various archives as well as some additional information about each of these archives. The Index TimeMap also lists the URI for which it provides an overview of potential TimeMap URIs, as well as the URI of the TimeGate and the TimeMap itself.
Response Example
Using the request http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com as an example, this would be a DIY TimeMap response. Note that the title attribute is (ab)used to provide additional information about archives:
<http://www.lamonitor.com>;rel="original", <http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com> ; rel="self" ; type="application/link-format", <http://timetravel.mementoweb.org/timegate/http://www.lamonitor.com> ; rel="timegate", <http://timetravel.mementoweb.org/can/timemap/link/http://www.lamonitor.com> ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:no|archive_id:gcwa", <http://timetravel.mementoweb.org/si/timemap/link/http://www.lamonitor.com> ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:no|archive_id:si", <http://web.archive.org/web/timemap/link/http://www.lamonitor.com> ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:yes|archive_id:ia", <http://archive.today/timemap/http://www.lamonitor.com> ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:yes|archive_id:archive.is" ...
 
Using the request http://timetravel.mementoweb.org/timemap/json/http://cnn.com/ as an example, this would be a TimeMap Index response. Note the use of special-purpose parameters to convey additional information about archives:
{ "original_uri": "http://www.lamonitor.com", "timegate_uri": "http://timetravel.mementoweb.org/timegate/http://www.lamonitor.com", "timemap_index": [ { "uri": "http://timetravel.mementoweb.org/can/timemap/link/http://www.lamonitor.com", "memento_compliant": "no", "archive_id": "gcwa" }, { "uri": "http://timetravel.mementoweb.org/si/timemap/link/http://www.lamonitor.com", "memento_compliant": "no", "archive_id": "si" }, { "uri": "http://archive.today/timemap/http://www.lamonitor.com", "memento_compliant": "yes", "archive_id": "archive.is" }, { "uri": "http://web.archive.org/web/timemap/link/http://www.lamonitor.com", "memento_compliant": "yes", "archive_id": "ia" } ], "timemap_uri": { "json_format": "http://timetravel.mementoweb.org/timemap/json/http://www.lamonitor.com", "link_format": "http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com" } }
3.2. "We Do It" TimeMap for access to version history
For the WDI TimeMap service, all information about Mementos in various archives is collected by the Time Travel service. If this information is readily available from cache, responses should be fast. If it is not, the information will be collected on the fly and, hence, a response may take a while. For both serialization formats, the nature of the TimeMap that will be provided depends on the amount of Mementos that are known to the Time Travel service:
Request
Simply append the format indicator (link or json) and the URI of the resource to the baseURL of the WDI TimeMap service.

http://labs.mementoweb.org/timemap/​format​/​URI
Request Example
Using http://www.w3.org/TR/webarch/ as an example URI, the WDI TimeMap formatted according to the application/link-format MIME type is requested as follows:

http://labs.mementoweb.org/timemap/link/http://www.w3.org/TR/webarch/

Using http://cnn.com as an example URI, the WDI TimeMap formatted according to the application/json MIME type is requested as follows:

http://labs.mementoweb.org/timemap/json/http://cnn.com/
Response
A TimeMap formatted according to the requested MIME type (​application/link-format or application/json​) that lists all Mementos for the requested resource known by the Time Travel service. The TimeMap also lists the URI for which it provides an overview of known Mementos, as well as the URI of the TimeGate and the TimeMap itself.
Response Example
Using the request http://labs.mementoweb.org/timemap/link/http://www.w3.org/TR/webarch/ as an example, this would be (an excerpt of) a TimeMap response:
<http://www.w3.org/TR/webarch/>; rel="original", <http://labs.mementoweb.org/timemap/link/http://www.w3.org/TR/webarch/> ; rel="self"; type="application/link-format" ; from="Wed, 11 Sep 2002 07:39:33 GMT" ; until="Fri, 10 Oct 2014 13:25:07 GMT", <http://timetravel.mementoweb.org/timegate/http://www.w3.org/TR/webarch/>; rel="timegate", <http://web.archive.org/web/20020911073933/http://www.w3.org/TR/webarch/> ; rel="first memento"; datetime="Wed, 11 Sep 2002 07:39:33 GMT", <http://web.archive.org/web/20021010101032/http://www.w3.org/TR/webarch/> ; rel="memento"; datetime="Thu, 10 Oct 2002 10:10:32 GMT", <http://web.archive.org/web/20021203004021/http://www.w3.org/TR/webarch/> ; rel="memento"; datetime="Tue, 03 Dec 2002 00:40:21 GMT", ....
 
Using the request http://labs.mementoweb.org/timemap/json/http://cnn.com/ as an example, this would be a TimeMap Index response:
{ "original_uri": "http://cnn.com/", "timegate_uri": "http://timetravel.mementoweb.org/timegate/http://cnn.com/", "timemap_uri": { "json_format": "http://labs.mementoweb.org/timemap/json/http://cnn.com/", "link_format": "http://labs.mementoweb.org/timemap/link/http://cnn.com/" }, "timemap_index": [ { "from": "2000-06-21T04:41:56Z", "until": "2005-05-12T22:25:15Z", "uri": "http://labs.mementoweb.org/timemap/1/json/http://cnn.com/" }, { "from": "2005-05-13T00:00:13Z", "until": "2010-10-05T20:30:51Z", "uri": "http://labs.mementoweb.org/timemap/2/json/http://cnn.com/" }, { "from": "2010-10-06T00:00:57Z", "until": "2014-12-20T12:22:34Z", "uri": "http://labs.mementoweb.org/timemap/3/json/http://cnn.com/" } ] }
4. TimeGate for datetime negotiation
The Time Travel service exposes a TimeGate for a resource with a given URI. A TimeGate, as defined in the Memento protocol (RFC 7089), supports datetime negotiation, a variant of content negotiation. Datetime negotiation allows direct access to an archived snapshot or a version of the resource as it existed at some desired datetime in the past. A brief description of TimeGates is available in the Introduction to Memento​.

When negotiating with a TimeGate, the desired datetime is provided in the Accept-Datetime HTTP request header. The TimeGate exposed by the Time Travel service will look for the Memento that is temporally closest to the desired datetime; it will include several web archives and content management systems in that lookup. Information about TimeGates for individual systems is available in the Memento Depot. This document details datetime negotiation with the aggregate TimeGate exposed by the Time Travel service.
Request
The request is an HTTP HEAD/GET against the TimeGate http://timetravel.mementoweb.org/timegate/​URI​, whereby URI is the URI of the resource for which a Memento is sought. The request includes an Accept-Datetime request header that provides the desired datetime expressed in GMT using the HTTP date format.
Request Example
Using http://www.ietf.org/ as an example URI, the cURL command to request a Memento with an archival/version datetime close to June 16 2012 is:
curl -I \ -H "Accept-Datetime: Sat, 16 Jun 2012 00:00:00 GMT" \ http://timetravel.mementoweb.org/timegate/http://www.ietf.org/
Response
The response has an HTTP "302 Found" status code and the URI of the selected Memento is provided in the Location header. It can be recognized to be the response of a TimeGate because of the Accept-Datetime value of the Vary header. The response also includes a Link header with links to the resource for which the TimeGate was accessed, to a TimeMap, to the selected Memento, as well as to the very first and most recent Memento if known to the Time Travel service.
Response Example
This is the response to the aforementioned cURL request:
HTTP/1.1 302 Found Date: Fri, 31 Oct 2014 20:44:44 GMT Content-Type: text/plain; charset=iso-8859-1 Content-Length: 0 Location: http://web.archive.org/web/20120616161314/http://www.ietf.org/ Vary: Accept-Datetime Link: <http://www.ietf.org/> ;rel="original" , <http://timetravel.mementoweb.org/timemap/link/1/http://www.ietf.org/> ; rel="timemap" ; type="application/link-format", <http://web.archive.org/web/20120616161314/http://www.ietf.org/> ; rel="memento" ; datetime="Sat, 16 Jun 2012 16:13:14 GMT", <http://web.archive.org/web/19961106114954/http://www.ietf.org/> ; rel="memento first" ; datetime="Wed, 06 Nov 1996 11:49:54 GMT", <http://web.archive.org/web/20140901131113/https://www.ietf.org/> ; rel="memento last" ; datetime="Mon, 01 Sep 2014 13:11:13 GMT"
5. Time Travel Prediction Service - List of DIY TimeMap and TimeGate URIs of a Memento
The Time Travel prediction service returns a list of TimeMap and TimeGate URIs of a Memento that may be exposed by archives. The response is based on a machine learning approach that tries to determine which archives hold Mementos for which URIs. This approach is similar to the approach explained in the DIY TimeMap service. The response does not provide information about actual Mementos and the client is left with the task of collecting this information by dereferencing the listed URIs. The machine learning prediction could also list URIs in archives that may not exist or could not list URIs from archives that may contain the Memento. The Time Travel approach is tuned to avoid the later scenario.

The response is delivered in JSON serialization with information that may be useful to a client to decide whether or not to dereference a potential URI:
Request
Simply append the desired URI of the resource to the baseURL of this JSON service.

http://timetravel.mementoweb.org/prediction/json/​URI
Request Example
Using http://cnn.com as an example URI, the JSON response is requested as:

http://timetravel.mementoweb.org/prediction/json/http://cnn.com
Response
A JSON document that lists potential TimeMap and TimeGate URIs in various archives as well as some additional information about each of these archives. The document also lists the URI for which it provides an overview of potential URIs.
Response Example
Using the request http://timetravel.mementoweb.org/prediction/json/http://cnn.com as an example, this would be a sample JSON response:
{ "original_uri": "http://cnn.com", "memento_info": [ { "timegate_uri": "http://web.archive.org/web/http://cnn.com", "timemap_uri": "http://web.archive.org/web/timemap/link/http://cnn.com", "memento_compliant": "yes", "archive_id": "ia" }, { "timegate_uri": "http://web.archive.bibalex.org/web/http://cnn.com", "timemap_uri": "http://web.archive.bibalex.org/web/timemap/link/http://cnn.com", "memento_compliant": "yes", "archive_id": "ba" }, { "timegate_uri": "http://www.webarchive.org.uk/wayback/archive/http://cnn.com", "timemap_uri": "http://www.webarchive.org.uk/wayback/archive/timemap/link/http://cnn.com", "memento_compliant": "yes", "archive_id": "blarchive" }, { "timegate_uri": "http://timetravel.mementoweb.org/can/timegate/http://cnn.com", "timemap_uri": "http://timetravel.mementoweb.org/can/timemap/link/http://cnn.com", "memento_compliant": "no", "archive_id": "gcwa" }, { "timegate_uri": "http://timetravel.mementoweb.org/aueb/timegate/http://cnn.com", "timemap_uri": "http://timetravel.mementoweb.org/aueb/timemap/link/http://cnn.com", "memento_compliant": "no", "archive_id": "aueb" }, { "timegate_uri": "http://timetravel.mementoweb.org/si/timegate/http://cnn.com", "timemap_uri": "http://timetravel.mementoweb.org/si/timemap/link/http://cnn.com", "memento_compliant": "no", "archive_id": "si" } ] }
6. Time Travel Archive Registry
The Time Travel service covers a range of web archives and version control systems both compliant and not compliant with the Memento protocol. The covered systems are listed in the Time Travel Archive Registry​. This list is provided as an XML file with a yet undocumented format. Still, many of the used parameter names should be self-explanatory for Memento developers.

In addition to the listed systems, the Time Travel service covers those that provide an explicit pointer to preferred TimeGates and/or TimeMaps, such as MediaWikis that have installed one of the Memento extensions for MediaWiki or systems that have implemented and personalized the generic TimeGate server software​.




To the extent possible under law, the person who associated CC0 with this work has waived all copyright and related or neighboring rights to this work.
 
Memento ProjectRobust LinksTime TravelMemento TracerWhat Did It Look Like
AboutAPIPrivacyTerms