The Celtic Coin Index

The Index has been built with the intention that people can query the database remotely and mash these data up for their own archaeological applications. I know there will be some keen people out there, for example Stuart Eve at LP Archaeology, Steve White of Online Archaeology and of course Andrew Larcombe (he’s already started.)

To do this, I have tried to create a REST API. What the hell is that I hear you cry! Well here’s two definitions:

Representational State Transfer (REST) is an architectural style for distributed hypermedia systems like the world wide web. The term originated in a 2000 doctoral dissertation about the web written by Roy Fielding, one of the principal authors of the HTTP protocol specification, and has quickly passed into widespread use in the networking community.
en.wikipedia.org/wiki/REST

A set of routines that an application uses to request and carry out lower-level services performed by a computer’s operating system. Also, a set of calling conventions in programming that define how a service is invoked through the application.
www.maptrax.com.au/

Does that make it any clearer? Probably not! Well this is how it works below and it opens up a world of possibilities….

Accessing the api is much the same as accessing the data via the advanced search interface. Each search page comes with the export functions built in for:

1. JSON - json.php This contains truncated point data via the api. Only records with spatial data are returned in this query.
2. XML - xmlDCN.php or xmlMIDAS.php - useful for transferring information between systems such as Historic Environment Record Offices or use by the Digital Coins Network. This contains truncated point data via the api.
   Available first week of June.
3. geoRSS (simple version at present) - georss.php I’ll be building a GML version shortly. This is produced in ATOM format and can be used for mapping as it contains truncated and obfuscated co-ordinates of the coins. Only records with spatial data are returned in this query.
4. KML - kml.php - for use in Google Earth or overlaying straight into Google maps with api 2.x or within Google’s new “My Maps” feature. This also contains truncated point data. Only records with spatial data are returned in this query.
5. RSS - rss.php - note this does not give spatial co-ordinates and is really just an RSS feed of coin number, county etc. This is limited to 25 records and is intended just for consumption on a website or through a feedreader. More details on RSS can be found on the BBC website or the PAS website.
6. CSV - csv.php - Good for downloading large chunks of the data. However this is limited in what you can download as there is sensitive data within the database. Still useful for many though. You cannot download via the api, the spatial co-ordinates.

However you can make a direct call to the RESTful API to access data. All requests take a number of parameters.


http://www.finds.org.uk/CCI/api/request_format.php?&variable=argument

The current version of the API is 1.0

If we make changes to the API, we’ll increase the version number and make details available. As the data is quite strictly controlled on a validated input methodology, the API will only be released with GET and not PUT, POST or DELETE . The database also contains one type of object - coins - so the requests are quite simple to process if you know what you are looking for. The variables that you can ask for are:

• Primary ruler - getRuler1
• Secondary ruler - getRuler2
• Region - getRegion
• Area - getArea
• Tribe - getTribe
• Denomination - getDenomination
• Metal type - getMetalType
• Coin number - getCoinNumber (very limited as it returns single records so don’t use other variables as you’ll get naff all unless you’re very precise.)
• Van Arsdell numbers - getVAType
• Allen Numbers - getAllenType
• Status - getStatus - very simple arguments “forgery or regular.”
• Collection held - getCollection
• Hoard coin - getHoardStatus - simple argument of 1 or 0 (true or false)
• Discovery method - getDiscoMethod
• Discovery year - getDiscoYear
• Set - getSet(only 2 options CCI or PAS - corresponds with the OAI server)
• County - getCounty - breaks down into English and Welsh counties.
• Country - getCountry - only options for this are: INDIA, IRAQ, ENGLAND, BELGIUM, FRANCE, LUXEMBOURG, WALES, SCOTLAND & SWITZERLAND. Coins have been found in a variety of countries and recorded at the CCI.

Due to the nature of the database, you cannot search by locality or parish at present.

The list of possible arguments is listed if you click on the variable name above, some are rather wide in scope, some are defined and narrow - eg hoard status argument is just binary 1 or 0.
Therefore you could either do a simple API call:

http://www.finds.org.uk/CCI/api/georss.php?getDenomination=Unit

This would return a feed on demand of all the coins in the Index where a denomination of unit has been recorded in the geoRSS format. You must supply an argument to retrieve data.

A more advanced spatial search could be applied:

http://www.finds.org.uk/CCI/api/georss.php?getDenomination=Unit&getCounty=Cambridgeshire

This query would return all records with the denomination of Unit and County of Cambridgeshire. I have a feeling that the geoRSS feed will be used the most as this will allow people to do geoMashups, which seem by far and away the most popular looking at the ProgrammableWeb matrix of currently available mashups.

At present, the API is authenticated and I’d like to keep it that way so that I can control who has access. If you would like to use the API, please contact me and I’ll sort out your authentication and I’d also like to know what you would be using these data for.

An example of what one could do?

Perhaps the most simple illustration of what could be done is consumption of an RSS feed and integration with your local society website. If you used the simplie pie architecture (don’t ever reinvent things!) you could have an RSS feed for recently found coins from Cambridgeshire.

Another mashup could be taking different denominations and overlaying them for a county to show patterns (in this case I have overlain Gold Staters from Cambs, Silver Units from Cambs and Units from Suffolk) and then these could be mashed up with Steve White’s KML layer of Roman villas.

Center of map

Gold Stater Cambs

Gold staters

Silver Unit Cambs

Silver Unit

Roman Villas from Online Archaeology

Villas

Silver unit Suffolk

Suffolk Units

Iron age objects recorded with the Scheme

Iron age objects

Have a click around in the above and see what you get in the bubbles. As I’m using a wordpress plugin, I can’t change the colours of the points to discriminate very easily.

This entry was posted on Wednesday, May 30th, 2007 at 11:24 am and is filed under API, Help. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.