| s | p_blank | o_blank |
|---|---|---|
| /id/statistical-geography/S01008928 | http://www.w3.org/1999/02/22-rdf-syntax-ns#type | geosparql: Geometry |
| /id/statistical-geography/S01008928 | geosparql: asWKT | POLYGON ((-3.2396531033797547 55.98323784233749, -3.240070213186883 55.98199090128963, -3.2398785430588397 55.98131689604523, -3.237862115653642 55.982308252589654, -3.2372888703739395 55.98184791326995, -3.2370490643302485 55.98068779597545, -3.2377194803220806 55.979599104591586, -3.2362593833011046 55.9797991023849, -3.235154695517185 55.978122586497065, -3.236857434946271 55.97774609067602, -3.2385361591050588 55.977332729332154, -3.2395093671997786 55.97735371178568, -3.239151897655774 55.97633029116254, -3.24105634100925 55.97675141781667, -3.244639346750066 55.9765445609579, -3.249173564153036 55.97651665785442, -3.2497454104373285 55.97637918679129, -3.250726797574177 55.976345761091736, -3.2511972080316136 55.976977349223546, -3.250883792746422 55.9775861899779, -3.2533458912490283 55.97728964322914, -3.253201536831985 55.97693447611906, -3.2547408973449206 55.97672068313168, -3.254170371897464 55.97543257591691, -3.253762774733539 55.97498160669113, -3.2575478167637555 55.974328882173786, -3.263041201706661 55.9735185137341, -3.26692172273238 55.97284910176306, -3.267479996222678 55.97277147698954, -3.2721675333381848 55.972058247050654, -3.2741945106307937 55.97327731143464, -3.276326098594392 55.97377641581895, -3.2772910020596275 55.97485367043918, -3.2784549157290694 55.97904682874395, -3.2766934884058316 55.98024599314238, -3.2723959452304534 55.98013748339331, -3.269352813477685 55.97975642614558, -3.2675992192084053 55.979845459600206, -3.264821710138255 55.979253094506284, -3.2631753748190198 55.97914148571048, -3.2620599385150597 55.97933801447328, -3.2599899517523827 55.98014542637225, -3.259620300124024 55.980902191079046, -3.254804012296913 55.982282072637496, -3.250604708565116 55.98376872256294, -3.2498148208793975 55.98387737205581, -3.2475901446312356 55.98372918543949, -3.246514404608014 55.98382093866445, -3.24367797667098 55.98353869304083, -3.2413280473977846 55.983531831028124, -3.2396531033797547 55.98323784233749)) |
The most flexible way to access the data is by using SPARQL, a query language, analagous to SQL for relational databases, for retrieving and manipulating data from graph databases like ours. We support SPARQL 1.1 query syntax. Many online tutorials are available.
To submit a SPARQL query from your code, you issue an HTTP GET or POST to our endpoint:http://statistics.gov.scot/sparql, with the query itself as a url-encoded parameter called query.
For example, to run the following simple SPARQL query and get the results as JSON:
SELECT * WHERE {?s ?p ?o} LIMIT 10Issue a POST to the endpoint, with the query in the body, and an Accept header of sparql-results+json:
POST http://statistics.gov.scot/sparql HTTP/1.1
Host: statistics.gov.scot
Accept: application/sparql-results+json
Content-Type: application/x-www-form-urlencoded
query=SELECT+%2A+WHERE+%7B%3Fs+%3Fp+%3Fo%7D+LIMIT+10Issue a GET to the following URL (note the .json extension - see the formats section for more detail on this):
GET http://statistics.gov.scot/sparql.json?query=SELECT+%2A+WHERE+%7B%3Fs+%3Fp+%3Fo%7D+LIMIT+10Scroll down to the end of this page for examples of both of these methods in a few different languages.
As with other aspects of our API, to get the data in different formats, you can use either (a) a format extension or (b) an HTTP Accept header. Available result formats depend on the type of SPARQL query. There are four main forms:
SELECT queries return tabular results, and the formats available reflect this:
| Format | Extensions | Accept Headers |
|---|---|---|
| XML | .xml |
application/xml, application/sparql-results+xml |
| JSON | .json |
application/json, application/sparql-results+json |
| Text | .txt, .text | text/plain |
| CSV | .csv | text/csv |
CONSTRUCT and DESCRIBE queries return graph data, so the results are available in the same formats as our resource APIs:
| Format | Extensions | Accept Headers |
|---|---|---|
| RDF/XML | .rdf | application/rdf+xml |
| N-triples | .nt, .txt, .text | application/n-triples, text/plain |
| Turtle | .ttl | text/turtle |
| JSON-LD | .json | application/ld+json, application/json |
ASK queries return a boolean result:
| Format | Extensions | Accept Headers |
|---|---|---|
| XML | .xml | application/xml, application/sparql-results+xml |
| JSON | .json | application/json, application/sparql-results+json |
| Text | .txt, .text | text/plain |
We accept page and per_page parameters for paginating the results of SELECT queries (we automatically modify your query to apply LIMIT and OFFSET clauses). For other query types (i.e. DESCRIBE, CONSTRUCT, ASK), pagination like this doesn’t make so much sense, so these parameters are ignored.
For requests made through the website (i.e. HTML format), the page size is defaulted to 20. For requests to our sparql endpoint for data formats (i.e. non-HTML), there will be no defaults for these parameters (i.e. results are unlimited. For performance reasons we generally advise LIMITing your query if possible).
You can parameterise your SPARQL by including %{tokens} in your queries, and providing values for the tokens in the request parameters.
Note that the following tokens are reserved and cannot be used as parameters for substitution:
controlleractionpageper_pageidcommitutf8queryOur servers are configured to allow access from all domains. This means that if you’re writing JavaScript to request data from our server in to a web page hosted on another domain, your browser should check this header and allow it.
If you need to support very old browsers, you can additionally pass a callback parameter and the results will be wrapped in that function. For example:
http://statistics.gov.scot/sparql.json?callback=myCallbackFunction&query=SELECT+%2A+WHERE+%7B%3Fs+%3Fp+%3Fo%7D+LIMIT+10This help topic on the jQuery website has more details.
Here’s a couple of examples running a query using the widely available cURL command line program.
Request the results as XML, using a POST:
curl -X POST -H "Accept: application/sparql-results+xml" -d "query=SELECT%20*%20WHERE%20%7B%3Fs%20%3Fp%20%3Fo%7D%20LIMIT%2010" http://statistics.gov.scot/sparqlRequest the results as JSON, using a GET:
curl -X GET -H "Accept: application/sparql-results+json" http://statistics.gov.scot/sparql?query=SELECT%20*%20WHERE%20%7B%3Fs%20%3Fp%20%3Fo%7D%20LIMIT%2010This example HTML page uses jQuery to issue a POST to our SPARQL endpoint, requesting the results as JSON.
<!DOCTYPE html>
<html lang='en'>
<head>
<script src='http://code.jquery.com/jquery-1.9.1.min.js'></script>
</head>
<body>
<script type='text/javascript'>
var query = 'SELECT * WHERE {?s ?p ?o} LIMIT 10';
var url = 'http://statistics.gov.scot/sparql.json';
$.ajax({
method: 'POST',
dataType: 'json',
url: url,
data: {query: query},
success: function(data) {
alert('success: ' + data.results.bindings.length + ' results');
console.log(data);
}
});
</script>
</body>
</html>