API (The Diary of Samuel Pepys)

There is an API for retrieving data about Diary Entries, and the Encyclopedia’s Categories and Topics.

NOTE: No registration is required to access the API and rate limits are 60 requests per minute. Please treat it gently: leave time between each request, and cache or save results to prevent repeated identical requests. If this becomes a problem for the site, registration and/or different rate limits may be introduced.

If you have questions or suggestions, please email me.

Browsable API
Formats
Endpoints
Changelog

1. Browsable API

You can explore the API in a web browser by starting at https://www.pepysdiary.com/api/v1/.

2. Formats

The API can return results in JSON or HTML format. There are two alternate methods for specifying the required format:

Accept HTTP headers:
- text/html for HTML
- application/json for JSON
The format query string parameter:
- ?format=html for HTML
- ?format=json for JSON

If both are specified, the Accept header takes precedence.

3. Endpoints

Brief info about each of the kinds of data – Diary Entries, Categories and Topics – can be retrieved as paginated lists. Further details about specific Entries, Categories and Topics can be retrieved by querying for items individually.

3.a. Diary Entries

There are Entries for most dates from 1st January 1660 to 31st May 1669 inclusive.

3.a.i. Entries List

Retrieve a list of Diary Entries (ordered from earliest to latest):

e.g. https://www.pepysdiary.com/api/v1/entries

Results format

{
  "totalResults": 3433,
  "totalPages": 69,
  "nextPageURL": "https://www.pepysdiary.com/api/v1/entries?page=2",
  "previousPageURL": null,
  "results": [
    {
      "date": "1660-01-01",
      "title": "Sunday 1 January 1659/60",
      "lastModifiedTime": "2021-05-03T18:07:06Z",
      "apiURL": "https://www.pepysdiary.com/api/v1/entries/1660-01-01",
      "webURL": "https://www.pepysdiary.com/diary/1660/01/01/"
    },
    # ...
  ]
}

Description of fields:

totalResults

The total number of Diary Entries across all pages of results.

totalPages

The number of pages of results (up to 50 Entries per page).

nextPageURL

The API URL for the next page of these results.

previousPageURL

The API URL for the previous page of these results.

results

An array of objects, each one representing a single Diary Entry.

date: The YYYY-MM-DD format date of this Entry.
title
: The human-readable title of this Entry.
lastModifiedTime: The last time this Entry was saved to the database (which doesn’t necessarily mean any data retrievable by the API was changed).
apiURL: The URL for the expanded Entry Instance data for this Entry.
webURL: The permalink to this Entry on pepysdiary.com.

Query string parameters

Alter the Entry List results returned by supplying one or more of these query string parameters:

Name	Default	Description	Example
`page`	`1`	Specify the page of results	`?page=2`
`start`	`1660-01-01`	The earliest date to fetch (YYYY-MM-DD)	`?start=1660-09-02`
`end`	`1669-05-31`	The latest date to fetch (YYYY-MM-DD)	`?end=1666-09-06`

Query string parameters can be combined, e.g.:

https://www.pepysdiary.com/api/v1/entries?start=1660-01-01&end=1660-12-31&page=2

3.a.ii. Entry Instance

Retrieve more data about a single Diary Entry with its YYYY-MM-DD format date:

e.g. https://www.pepysdiary.com/api/v1/entries/1660-01-01

Results format

{
  "date": "1660-01-01",
  "title": "Sunday 1 January 1659/60",
  "entryHTML": "<p>Blessed be God, at the end of the last year I was in very good health, without any sense of my old pain, but upon taking of cold.<sup id=\"fnr1-1660-01-01\"><a href=\"#fn1-1660-01-01\">1</a></sup></p>\r\n\r\n<p>I lived in <a href=\"http://www.pepysdiary.com/encyclopedia/6919/\">Axe Yard</a> having ... <a href=\"http://www.pepysdiary.com/encyclopedia/2408/\">Madam Morrice</a>, and supt with us.  After that my wife and I went home with them, and so to our own home.</p>",
  "footnotesHTML": "<p>The year did not legally begin in ... <li id=\"fn3-1660-01-01\">\"The City sent and invited him [Monk] to dine the next day at <a href=\"http://www.pepysdiary.com/encyclopedia/129/\">Guildhall</a>, and there he declared for the members whom the army had forced away in year forty-seven and forty-eight, who were known by the names of secluded members.\" -- Burnet's Hist. of his Own Time, book i. <a href=\"#fnr3-1660-01-01\">↩</a></li>\r\n</ol>",
  "annotationCount": 72,
  "lastAnnotationTime": "2021-05-03T18:07:06Z",
  "topics": [
    "https://www.pepysdiary.com/api/v1/topics/6919",
    "https://www.pepysdiary.com/api/v1/topics/346",
    "https://www.pepysdiary.com/api/v1/topics/275",
    # ...
  ],
  "lastModifiedTime": "2021-05-03T18:07:06Z",
  "apiURL": "https://www.pepysdiary.com/api/v1/entries/1660-01-01",
  "webURL": "https://www.pepysdiary.com/diary/1660/01/01/"
}

Description of fields:

date: The YYYY-MM-DD format date of this Entry.
title
: The last time this Entry was saved to the database (which doesn’t necessarily mean any data retrievable by the API was changed).
entryHTML
: The full HTML for this Entry’s text. It will usually contain links to Encyclopedia Topics, possibly to other Diary Entries, and sometimes #anchor links to footnotes contained in footnotesHTML.
footnotesHTML
: The HTML for any optional footnotes to the Entry. Often an empty string.
annotationCount
: The number of annotations written about the Entry.
lastAnnotationTime
: The time the most recent annotation was written about the Entry.
topics
: An array of API URLs for all Encyclopedia Topics linked to in the Entry’s entryHTML and footnotesHTML.
lastModifiedTime: The last time this Entry was saved to the database (which doesn’t necessarily mean any data retrievable by the API was changed).
apiURL: The URL for the expanded Entry Instance data for this Entry.
webURL: The permalink to this Entry on pepysdiary.com.

Query string parameters

None.

3.b. Encyclopedia Categories

This site’s Encyclopedia is made up of a hierarchical tree structure of Categories, each of which contains zero or more Topics.

Retrieve a list of Encyclopedia Categories (ordered alphabeticaly by slug):

e.g. https://www.pepysdiary.com/api/v1/categories

Results format

{
  "totalResults": 86,
  "totalPages": 2,
  "nextPageURL": "https://www.pepysdiary.com/api/v1/categories?page=2",
  "previousPageURL": null,
  "results": [
    # ...
    {
      "slug": "food",
      "title": "Food",
      "topicCount": 14,
      "depth": 2,
      "parents": [
        "https://www.pepysdiary.com/api/v1/categories/fooddrink"
      ],
      "children": [
        "https://www.pepysdiary.com/api/v1/categories/baked",
        "https://www.pepysdiary.com/api/v1/categories/dairy",
        "https://www.pepysdiary.com/api/v1/categories/fruitveg",
        "https://www.pepysdiary.com/api/v1/categories/herbs",
        "https://www.pepysdiary.com/api/v1/categories/meat",
        "https://www.pepysdiary.com/api/v1/categories/seafood"
      ],
      "apiURL": "https://www.pepysdiary.com/api/v1/categories/food",
      "webURL": "https://www.pepysdiary.com/encyclopedia/fooddrink/food/"
    },
    # ...
  ]
}

Description of fields:

totalResults

The total number of Categories across all pages of results.

totalPages

The number of pages of results (up to 50 Categories per page).

nextPageURL

The API URL for the next page of these results.

previousPageURL

The API URL for the previous page of these results.

results

An array of objects, each one representing a single Encyclopedia Category.

slug: The unique and unchanging URL slug used as the Category’s identifier.
title
: The human-readable title of this Category.
topicCount: The number of Topics within this Category. 0 or more. Fetch an individual Category Instance for a full list of their API URLs.
depth: The Category’s numerical position within the hierarchical tree structure. Categories at the top level have a depth of 1, their children have a depth of 2, etc.
parents: An array of API URLs for any Categories immediately above this one in the tree structure, if any.
children: An array of API URLs for any Categories immediately below this one in the tree structure, if any.
apiURL: The URL for the expanded Category Instance data for this Category.
webURL: The permalink to this Category on pepysdiary.com. Note that the URLs are constructed using this Category’s slug and those of all Categories above it.

Query string parameters

Alter the Category List results returned by supplying a query string parameter:

Name	Default	Description	Example
`page`	`1`	Specify the page of results	`?page=2`

3.b.ii. Category Instance

Retrieve more data about a single Encyclopedia Category with its slug:

e.g. https://www.pepysdiary.com/api/v1/categories/food

Results format

{
  "slug": "food",
  "title": "Food",
  "topicCount": 14,
  "depth": 2,
  "parents": [
    "https://www.pepysdiary.com/api/v1/categories/fooddrink"
  ],
  "children": [
    "https://www.pepysdiary.com/api/v1/categories/baked",
    "https://www.pepysdiary.com/api/v1/categories/dairy",
    # ...
  ],
  "topics": [
    "https://www.pepysdiary.com/api/v1/topics/944",
    "https://www.pepysdiary.com/api/v1/topics/1044",
    # ...
  ],
  "apiURL": "https://www.pepysdiary.com/api/v1/categories/food",
  "webURL": "https://www.pepysdiary.com/encyclopedia/fooddrink/food/"
}

Description of fields:

slug: The unique and unchanging URL slug used as the Category’s identifier.
title
: The human-readable title of this Category.
topicCount: The number of Topics within this Category. Zero or more. Fetch an individual Category Instance for a full list of their API URLs.
depth: The Category’s numerical position within the hierarchical tree structure. Categories at the top level have a depth of 1, their children have a depth of 2, etc.
parents: An array of API URLs for any Categories immediately above this one in the tree structure, if any.
children: An array of API URLs for any Categories immediately below this one in the tree structure, if any.
topics: An array of API URLs of the Topics within this Category, if any.
apiURL: The URL for the expanded Category Instance data for this Category.
webURL: The permalink to this Category on pepysdiary.com. Note that the URLs are constructed using this Category’s slug and those of all Categories above it.

Query string parameters

None.

3.c. Encyclopedia Topics

This site’s Encyclopedia is made up of a hierarchical tree structure of Categories, each of which contains zero or more Topics.

3.c.i. Topics List

Retrieve a list of Encyclopedia Topics (in ascending order by id):

e.g. https://www.pepysdiary.com/api/v1/topics

Results format

{
  "totalResults": 5082,
  "totalPages": 102,
  "nextPageURL": "https://www.pepysdiary.com/api/v1/topics?page=2",
  "previousPageURL": null,
  "results": [
    {
      "id": 29,
      "title": "Samuel Pepys",
      "orderTitle": "Pepys, Samuel",
      "kind": "person",
      "lastModifiedTime": "2020-12-21T16:26:29Z",
      "apiURL": "https://www.pepysdiary.com/api/v1/topics/29",
      "webURL": "https://www.pepysdiary.com/encyclopedia/29/"
    },
    # ...
  ]
}

Description of fields:

totalResults

The total number of Topics across all pages of results.

totalPages

The number of pages of results (up to 50 Topics per page).

nextPageURL

The API URL for the next page of these results.

previousPageURL

The API URL for the previous page of these results.

results

An array of objects, each one representing a single Encyclopedia Topic.

id: The unique, unchanging, numeric ID of this Topic.
title: The human-readable title of this Topic.
orderTitle: A version of title that can be used for ordering Topics in a way that makes more sense. e.g. "The" and "A" are at the end of the string, and people names are like "Pepys, Samuel".
kind: One of person, place or default (for all Topics that aren’t people or places).
lastModifiedTime: The last time this Topic was saved to the database (which doesn’t necessarily mean any data retrievable by the API was changed).
apiURL: The URL for the expanded Topic Instance data for this Topic.
webURL: The permalink to this Topic on pepysdiary.com.

Query string parameters

Alter the Topic List results returned by supplying a query string parameter:

Name	Default	Description	Example
`page`	`1`	Specify the page of results	`?page=2`

3.c.ii. Topic Instance

Retrieve more data about a single Encyclopedia Topic with its id:

e.g. https://www.pepysdiary.com/api/v1/categories/food

Results format

{
  "id": 106,
  "title": "Sir George Downing",
  "orderTitle": "Downing, Sir George",
  "wheatleyHTML": "<p>George Downing was one of ... somewhat of a mixed kind. He died in July, 1684.</p>",
  "tooltipText": "1623-1684. An Anglo-Irish soldier, ... modern-day Downing Street is built.",
  "wikipediaURL": "https://en.wikipedia.org/wiki/Sir_George_Downing%2C_1st_Baronet",
  "thumbnailURL": "https://pepysdiary-production.s3.amazonaws.com/media/encyclopedia/thumbnails/106.jpg",
  "annotationCount": 29,
  "lastAnnotationTime": "2016-01-08T02:06:14Z",
  "kind": "person",
  "latitude": null,
  "longitude": null,
  "zoom": null,
  "shape": "",
  "categories": [
    "https://www.pepysdiary.com/api/v1/categories/people"
  ],
  "entries": [
    "https://www.pepysdiary.com/api/v1/entries/1660-01-01",
    "https://www.pepysdiary.com/api/v1/entries/1660-01-07",
    "https://www.pepysdiary.com/api/v1/entries/1660-01-16",
    # ...
  ],
  "lastModifiedTime": "2020-12-21T16:25:12Z",
  "apiURL": "https://www.pepysdiary.com/api/v1/topics/106",
  "webURL": "https://www.pepysdiary.com/encyclopedia/106/"
}

A Topic with a kind of place may have its geographic fields populated, as in this example snippet, from Topic ID 125 (Lincoln’s Inn Fields; see in the Encyclopedia):

  "latitude": 51.516257,
  "longitude": -0.116594,
  "zoom": 15,
  "shape": "51.517232,-0.115517;51.516137,-0.114992;51.515924,-0.115158;51.515426,-0.117261;51.51547,-0.117636;51.516354,-0.118328;51.516511,-0.118302;51.516658,-0.118098;51.517232,-0.115517",

Description of fields:

id: The unique, unchanging, numeric ID of this Topic.
title: The human-readble title of this Topic.
orderTitle: A version of title that can be used for ordering Topics in a way that makes more sense. e.g. "The" and "A" are at the end of the string, and people names are like "Pepys, Samuel".
wheatleyHTML: Text taken from a footnote in the 1893 edition of the diary by Henry B. Wheatley that was about this Topic. Could be an empty string. For example, "<p>An olio is a mixed dish of meat and vegetables, and, secondarily, mixture or medley.</p>"
tooltipText: A brief plaintext string summarising the topic, as used in the pop-up "tooltips" on this site. Could be an empty string.
wikipediaURL: A corresponding URL on Wikipedia for this Topic. Contains no HTML. Could be an empty string.
thumbnailURL: The URL for a 100×120 pixel image for this Topic. Only present for people, if at all, otherwise an empty string. It’s possible the URLs may change in future. All images are cropped from images found on Wikipedia. If you plan to display these images, please save and use local copies, rather than displaying from these URLs directly.
annotationCount: The number of annotations written about the Topic.
lastAnnotationTime: The time the most recent annotation was written about the Topic.
kind: One of person, place or default (for all Topics that aren’t people or places).
latitude: A place might have a decimal representing its latitude. Otherwise, null.
longitude: A place might have a decimal representing its longitude. Otherwise, null.
zoom: A place might have an integer zoom level, indicating a useful initial zoom when displaying it on a map. Otherwise, null.
shape: A place that represents a line or area may have a series of latitude, longitude pairs. If it’s an area the first and last pairs will be identical. Otherwise, an empty string.
categories: An array of API URLs for the Categories this Topic is in (usually one Category but sometimes more).
entries: An array of API URLs for the Diary Entries in which this Topic is mentioned.
lastModifiedTime: The last time this Topic was saved to the database (which doesn’t necessarily mean any data retrievable by the API was changed).
apiURL: The URL for the expanded Topic Instance data for this Topic.
webURL: The permalink to this Topic on pepysdiary.com.

Query string parameters

None.

4. Changelog

2021-08-09: Launch

Contents

1. Browsable API

2. Formats

3. Endpoints

3.a. Diary Entries

3.a.i. Entries List

Results format

Description of fields:

Query string parameters

3.a.ii. Entry Instance

Results format

Description of fields:

Query string parameters

3.b. Encyclopedia Categories

3.b.i. Categories List

Results format

Description of fields:

Query string parameters

3.b.ii. Category Instance

Results format

Description of fields:

Query string parameters

3.c. Encyclopedia Topics

3.c.i. Topics List

Results format

Description of fields:

Query string parameters

3.c.ii. Topic Instance

Results format

Description of fields:

Query string parameters

4. Changelog