API

This discribes the Arts Holland API. Arts Holland offers both a SPARQL endpoint and a REST API.

SPARQL

All Arts Holland data can be accessed using SPARQL, a query language for RDF data. By submitting SPARQL queries to the SPARQL endpoint, you can retrieve exactly the data you need. More information about SPARQL is found in the W3C SPARQL specification.

The SPARQL endpoint is http://api.artsholland.com/sparql.

RDF vocabulary

An RDF vocabulary is available for in-depth information about the Arts Holland data model. Also, a basic description of the Arts Holland data model can be found in the REST API documentation below.

Tutorial

Besided this document, you can use the interactive SPARQL tutorial to guide you through the Arts Holland data, data model and the SPARQL queries you can use to access all the data.

SPARQL requests

SPARQL queries can be submitted to the database server by doing a GET or POST request to /sparql and URL encoding the SPARQL query in the query parameter.

Make sure to set the Content-Type header to application/x-www-form-urlencoded and the Accept header to a media type from the table in the next section.

Response formats

You can select one of the response data formats by setting the Accept header to the appropriate media type, or by appending an file extension to the request.

If you want to view the result in your browser, you can overwrite the response media type to text/html by specifying the request parameter plaintext=true.

SPARQL browser

Arts Holland also provides a web-based SPARQL browser. You can use this browser to test SPARQL queries or just to get an impression about the data available in the Arts Holland database.

RDF namespaces

The SPARQL browser automatically appends a set of default RDF namespace prefixes to all submitted SPARQL queries, something that you have to do yourself when doing direct GET or POST requests. Alternatively, you can rewrite your queries and use full URIs instead of namespaced ones.

For example, see the two following queries. With namespaces:

PREFIX ah: <http://purl.org/artsholland/1.0/>
PREFIX dc: <http://purl.org/dc/terms/>
SELECT ?venue ?title {  
  ?venue a ah:Venue ;
    dc:title ?title .
} LIMIT 10

Without namespaces:

SELECT ?venue ?title {  
  ?venue a <http://purl.org/artsholland/1.0/Venue> ;
    <http://purl.org/dc/terms/title> ?title .
} LIMIT 10

Example request

The following query, for example, retrieves the URIs and English titles of 25 venues in Amsterdam from the Arts Holland database.

SELECT DISTINCT ?venue ?title
WHERE { 
  ?venue a ah:Venue .
  ?venue dc:title ?title .
  ?venue ah:locationAddress ?address .
  ?address vcard:locality "Amsterdam" . 
  FILTER(langMatches(lang(?title), "en"))
} ORDER BY ?venue
LIMIT 25

You can paste this query in the Arts Holland SPARQL browser, or directly do a GET or POST request to the SPARQL endpoint. In the latter case, don’t forget to add the following namespace prefixes:

PREFIX ah: <http://purl.org/artsholland/1.0/>
PREFIX dc: <http://purl.org/dc/terms/>
PREFIX vcard: <http://www.w3.org/2006/vcard/ns#>

Full text search

You can use the full text search functionality of the uSeekM library to do a full text search in the Arts Holland database. uSeekM text search currently only indexes dc:description and dc:title properties.

Geo-spatial search

The uSeekM library is also used to add geo-spatial computations and indexing its database. This functionality can be used in all SPARQL queries submitted to the Arts Holland SPARQL endpoint. More documentation can be found in the uSeekM wiki.

REST API

Accessing Arts Holland using the SPARQL endpoint provides the most flexibility, but its query language and response formats might sometimes be too complex and overwhelming. Therefore, Arts Holland also provides a easy to use REST API with which you can access the most important parts of the Arts Holland semantic Open Linked Database.

The REST API endpoint is http://api.artsholland.com/rest.

Data model

The REST API only discloses the main elements in the Arts Holland database: events, productions and venues. If you want to access all the other data (such as information about hotels, restaurants and public transport stops) or if you want more control over the exact query and returned data, you can use the SPARQL endpoint.

The objects returned by the REST API are described below in short.

Main elements

Events, venues and productions are identified by a CIDN number managed by the Nederlands Uitburo.

Other elements

URI structure

Object lists

Single objects

Child elements and relations

Filters

Filters only work on first level main element API requests (e.g. /rest/event, /rest/venue and /rest/production).

Response formats

You can select one of the response data formats by setting the Accept header to the appropriate media type, or by appending an file extension to the request.

If you want to display API results in your browser, you can override the response media type by setting plaintext=true. This parameter will set the response media type to text/html, which your browser will nicely display instead of download to file.

JSONP is also supported: all REST API JSON results can be encapsulated in a JavaScript function call by setting callback={callback}.

Localization

Text strings in the Arts Holland database are often localized, and available in more than one language (mostly Dutch and English). By specifying an IETF language tag parameter lang={tag} in the request URI it is possible to let the REST API only return strings in the specified language. Not all strings in the database are localized; those strings will always be returned, regardsless of the specified language tag.

The language parameter defaults to English (i.e. lang=en). Language filtering can be disabled by specifying lang=any.

Pagination

API requests that can return more than one object are always paginated. Two URI parameters are available to control pagination: per_page={per_page}&page={page}.

The parameter {per_page} specifies the number of desired results per page, and {page} the desired page. The default results per page is 10.

If JSON is the desired return format of the request, paginated requests return pagination metadata in a dedicated JSON object:

{
  "metadata": {
    "page": 3,
    "per_page": 15,
    ...
  },
  "results": [
    ...
  ]
}

Ordering

The REST API returns unordered results by default. This usually works fine for most applications, especially with filtered requests with small result sets. If your application, however, does require the results to be ordered, you can specify ordered=true in the request. The system will order the resulting objects by URI.

Please be warned that ordering has a performance impact, and will result in longer response times.

Counting

The REST API will return the total number of available results for paged queries if count=true is added to the request parameters. The result will then include count metadata for that specific query, including filters:

{
  "metadata": {
    "count": 718,
    ...
  },
  "results": [
    ...
  ]
}

Counting will result in much longer response times as the REST API back-end has to submit the same query to the database twice; one time for counting the total number or results and one time for returning the data.

The count parameter only works for requests where JSON is the desired return format.

Pretty-printed JSON results

The REST API will pretty-print the JSON it produces if the pretty=true request parameter is used.

Again, this parameter only works for JSON requests.

Example requests