SOAP details

SOAP is an industry standard protocol in wide use for exchanging data between computer systems. It’s often called just Web Services, and lies at the heart of the Service Oriented Architecture ideas underpinning much of the systems in development today.

Unlike our other data feeds, the SOAP feed gives you considerable control over what data you get back from us: it allows you to specify searches and other detailed queries into our data. With it, you can build our systems directly into your live enduser services. Or you can – as with our other feeds – harvest our data into your systems and then deliver it to your users from your own repository.


 

Our SOAP API

All SOAP services are described by an XML document called a WSDL (WebServices Description Language). The WSDL sets out the kinds of data which can be exchanged with a SOAP server, and the methods (commands) which can be requested.

The Culture24 SOAP data feed’s WSDL is available here. You’ll need to find a development environment or web services toolkit to use, and then you can load our WSDL into it and get programming!

The Culture24 SOAP data feed has just a single method, SearchRetrieve. You pass in a cluster of data called a SearchRetrieveRequest, and you get back a SearchRetrieveResponse. The SearchRetrieveRequest contains the query you’d like to pass to Culture24; the SearchRetrieveResponse contains Culture24′s answer – this is where you’ll get actual Culture24 content delivered to you.


 

SearchRetrieveRequest

SearchRetrieveRequest contains the following members; you need to fill these elements in your programme, and pass them to Culture24′s SearchRetrieve service:

  • profile: this is a string and indicates what kind of search request you’reasking to do. Always set this to “c24”.
  • query: this is the search itself. It is an array of context/value pairs.Basically, the contexts are things you want to search, and the values that you want to search for. For example, one context might be “fromdate”, and the value would be a date. That would restrict the request to records dated after that date. See below for a full list of the search contexts which you can use.
  • startRecord: this is a positive number which tells Culture24 which record you want back first. Records before this one are skipped and not returned to you. Using startRecord and maximumRecords, you can step through large result sets bit by bit. If in doubt, set startRecord to 1.
  • maximumRecords: this is a non-negative number which tell Culture24 how many records to return to you. If your search finds more than this number of records, then only this many will be sent back to you: the rest will be skipped.

 

SearchRetrieveResponse

When you send a SearchRetrieveRequest to the Culture24 SOAP data feed, you will get a SearchRetrieveResponse back. This contains the Culture24 content which you asked for. {The following fields are included: (there are a couple of extra fields in there, but they don’t contain useful information):

  • numberOfRecords: Culture24 sets this to the total number of records which match your search criteria. If you set a small maximumRecords value, you will still get the total number of hits in the entire Culure24 repository here.
  • records: a list of Culture24 records. Each record contains a name, a fullname, and a list of fields. The name and fullname refer to the type of record being returned. It will be set to things like venue, article, event, etc. Each field also contains a name – field names such as longitude or openingHours – and a fullname intended for display such as “Longitude” or “Opening hours”. A field also contains a value, which contains the actual Culture24 content (finally!). The records and fields you get back are listed in the data feed field lists here.

 

Search Contexts

The searches you send into the Culture24 SOAP datafeed can choose from a set of search contexts. These are strings which specify what things you want to search (like text, dates, id’s, etc.). As we get feedback from users of this service, we might add more search contexts to the list to enable more complex searches to be specified.

Culture24 SOAP datafeed currently supports these search contexts:

  • recordtype: the kind of record you’re looking for: this can be any of theserecord types: events, venues, articles, websites, or resources
  • from: a start date: no records will be returned before this date
  • until: a “to” date: no records will be returned after this date
  • key: this isn’t really a search context: this is how you tell our server what kind of access you want to our content. Use “open” to get the normal summary data feed. If you need access to more of our content than the summary feed provides, contact us and we’ll let you have a key which you can use here. That will allow you to get a Full feed of our data. While you’re waiting for a key or if you’re wanting to get on and develop some stuff straightaway, you can use the key “redacted”, which will give you access to the full feed, but some of the data will be overwritten with underscore characters.
FOO