Using the API

API

Application Programming Interfaces, or APIs are part of services known as middleware. This means they're intended to be used by another application - a script, or a web site.

You can use the AddressingHistory API to search AddressingHistory's database of Post Office Directories (for information please refer to the Terms and Conditions). This allow you to download and use the results in another website or application such as Google Earth. Queries are made as HTTP GET requests, in the same way web browsers request webpages - using URL parameters to specify the search parameters and output format.

Getting started

Requests can be made to search the AddressingHistory database using your web browser, script or software, with combinations of the following parameters:

  • forename, search for entries with a specific forename.
  • surname, search for entries with a specific surname.
  • address, search for entries by street name / address.
  • profession, search for professions such as e.g. 'surgeon', 'baker'.
  • category, search for categories of professions e.g. 'Medical', 'Merchant'.
  • id, return a single directory entry by its identification number.
  • directory, restrict your search to a single directory e.g. '1865'.
  • maxRows, limit the number of results returned.
  • boundingBox [Required], map extents to limit search. e.g.:
    • Aberdeen: boundingBox=-2.345,57.067,-1.875,57.216
    • Edinburgh: boundingBox=-3.417,55.867,-2.947,56.021
    • Glasgow: boundingBox=-4.498,55.780,-4.028,55.935
    • Scotland: boundingBox=-8.084,55.429,-0.570,57.845

You can also choose to see the results in different formats by using a different 'format' parameter in your request.

  • kml, to see KML data suitable for import into Google Earth.
  • json, for a Javascript Object Notation suitable for re-use in web applications (default).
  • txt, for a plain-text represetation, using commas to separate the data.

Sample Requests

Search for all the entries with the surname 'Arnott' in Scotland (boundingBox=-8.084,55.429,-0.570,57.845) and return the results in KML format, looks like this:

http://addressinghistory.edina.ac.uk/ws/search
?surname=Arnott
&boundingBox=-8.084,55.429,-0.570,57.845
&format=kml

Search for all the entries with the surname 'Hamilton' in Edinburgh (boundingBox=-3.417,55.867,-2.947,56.021) in '1905' and limit the search results to '5', looks like this:

http://addressinghistory.edina.ac.uk/ws/search
?surname=Hamilton
&boundingBox=-3.417,55.867,-2.947,56.021
&directory=1905
&maxRows=5

Sample Result

Here's a sample of a Post Office Directory entry in JSON format:

{
   "type" : "AddressingHistory Search Results",
   "results" : [
   {
      "type" : "Post Office Directory Entry",
      "id" : "182329",
      "properties" : {
         "forename" : "Thomas Duddingston",
         "surname" : "Wilson M.A., M.B., F.R.C.S.E.",
         "address" : "West Newington house, 10 Newington road, Edinburgh, Scotland",
         "profession" : "physician and surgeon",
         "category" : "Q",
         "town" : "Edinburgh",
         "directory" : "1905",
         "section" : "General Directory",
         "page" : "512",
         "googleLat" : "55.9389119",
         "googleLon" : "-3.1793456",
         "googleAccuracy" : "8",
         "useridMod" : "admin",
         "lastModified" : "2011-09-02"
      }
   } ],
   "totalResults": "1"
}
			
AddressingHistory Blog