Technical overview

The content on our Culture24 website is also available as electronic data feeds. This allows you and others to build Culture24 data into your services and systems.

Much of our data is available right now: you can go ahead and use it, but please refer to our terms and conditions. The rest of the data – for example the full text of our news articles – is also available right now, but those feeds have been “redacted”, that is, some of the data has been made unreadable (by replacing all the letters by underscores).

To access a full feed of this content, get in touch with us, and we will talk.

Meanwhile, you can use the redacted feeds to base your developments on. We support a number of different feeds, described below. Take a look and choose the one which is best suited to what you want to do and your skills and experience.

Detailed descriptions of the data fields here.

 

RESTful-API

Culture24 now offers a RESTful-API to its event and venue data, providing an easy way for cultural listings to be included in websites or mobile applications.  The service was developed in response to the needs of a range of Culture 24 data-sharing clients, including GransNet and The World War One Centenary Programme, led by IWM.  Please see the Culture24 REST API Developer’s Guide 1.4  for more information.

OAI-PMH

The Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) is a beautiful protocol for harvesting – i.e. for taking and maintaining a copy of the bit of our content you are interested in. It allows you to take a complete dump of the data, and it has great support for coming back later on and getting just the things which have changed recently.

The protocol runs over ordinary HTTP, and it defines what URLs you can pass in to ask for stuff, and what kind of stuff you’ll get back. All the data coming back is in XML.

There are three versions of the feed, the open feed, the redacted full feed, and the full feed. The open feeds give you all the venues, summaries of all the articles, great pointers to resources and lots more. The full feeds give you all this plus the full text of our news articles, more details about venues, and more.

Take a look at the protocol at www.openarchives.org/OAI/openarchivesprotocol.html.

 

RSS

RSS (often said to be an abbreviation of Really Simple Syndication) is a simple way to get hold of lists of recent articles, events, and other Culture24 content. It’s a great way to get hold of up to date information. You’ll see the little RSS icon on many of the Culture24 pages – just click on these and your browser will keep you up to date with what’s happening in that bit of Culture24.

You can also use RSS as a data feed and use it to feed automatically into systems you are building or maintaining – we’re using RSS version 2.0.1.

Take a look around the site and pick any or all of the feeds in the areas which are of most interest to you and your projects. The Culture24 home page always has an RSS feed attached to it, and the URL of the feed itself is http://www.culture24.org.uk/latest.rss.

 

SOAP

Often called Web Services, SOAP is one of the industry standard API protocols in use today. Just like with our OAI feeds, we have three SOAP feeds, the open feed, a redacted full feed, and the full feed.

All SOAP APIs have an XML description called a WSDL which sets out how to use the API. You can find ours here.

Load the WSDL into your development IDE and you can start using Culture24 data in your systems right now. Our WSDL features a search language which allows you to build specific queries into your application, and an interface for accessing our content.

Let’s play!

OK – time to play. OAI data feeds aren’t intended for direct human consumption, but they ship up XML over HTTP, so you can point your web browser at the feed and you’ll be able to see recognizable stuff in the XML which you get back.

The Culture24 summary OAI-PMH feed is at http://www.culture24.org.uk/api/oai/open. The OAI protocol works by specifying what you need to add on the end of this base URL. Here are some examples – try them out.

http://www.culture24.org.uk/api/oai/open?verb=Identify will return some basic technical information about the feed, including, for example, who to contact if you have any questions.

http://www.culture24.org.uk/api/oai/open?verb=ListMetadataFormats asks the server which different record formats it supports (OAI-PMH calls these metadata formats. If you run this request, you’ll be able to see that the Culture24 OAI server supports two formats: the oai_dc format, and the c24 format. Oai_dc is a Dublin Core version of the records – supporting that is a basic requirement of OAI: all OAI-PMH servers need to support that. c24 is the morenative format where you’ll see our data with more detail and precision.

http://www.culture24.org.uk/api/oai/open?verb=ListSets will ask the server to list all the sets it knows about. It will respond saying it knows about events, venues, articles, websites, and resources

Right: finally, let’s get some real data! http://www.culture24.org.uk/api/oai/open?verb=ListRecords&metadataPrefix=c24&set=resources. This says: “I want your resources, and I’d like them in Culture24 format.” You’ll get a whole bunch of (quite small) records back. At the end, you’ll see something called a Resumption Token. This is OAI’s way of saying: “I’ve got lots of records here: here are the first lot; if you want more, post this resumption token back and I’ll pick up where I left off.” This is a really efficient way to transmit big datasets – your XML parser won’t fall over because it had a huge document to parse; on the other hand you don’t have to take records one by one, which can be really slow (though OAI does provide a way to do that if you want). While you’re in there, notice that every record has a little header section, which includes a date stamp (last modified date), and an identifier.

The identifier is guaranteed to be unique to this record. So you can store that in your system and rely on Culture24 using the same identifier next time you happen across the same record. Check out the description of the protocol at http://www.openarchives.org/OAI/openarchivesprotocol.html for more details of what you can do with OAIPMH.

 

Full and Redacted feeds

So far we’ve been looking at the summary feed. We also publish a full feed, which includes more fields, including, for example, the full text of our news articles, and lots of other stuff. To get access to the full feed, you need a key. Get in touch with us for more information about this.

Meanwhile, to allow you to get going immediately, we have a special version of the full feed which we call the redacted feed. This is exactly the same as the full feed, except some of the data has been overwriten with underscore characters.

The redacted feed is at http://www.culture24.org.uk/api/oai/redacted. When you get a real key from us, just put it at the end of the URL in place of the word “redacted”. For example, if your key turns out to be KGxX17tta, then your full feed URL will be ‘http://www.culture24.org.uk/api/oai/KGxX17tta’. You can try out all the URLs above on the redacted feed. Check out, for example, http://www.culture24.org.uk/api/oai/redacted?verb=ListRecords&metadataPrefix=c24&set=resources