| s | p_blank | o_blank |
|---|---|---|
| /id/statistical-geography/S01007009 | http://www.w3.org/1999/02/22-rdf-syntax-ns#type | geosparql: Geometry |
| /id/statistical-geography/S01007009 | geosparql: asWKT | POLYGON ((-2.774926096296395 57.4485432389282, -2.7747464007549163 57.447924513079116, -2.7750369096047875 57.44669207548123, -2.7757002837174243 57.44609968458827, -2.7768110060748024 57.44630242403933, -2.777143877065752 57.44588721117891, -2.7749572903682562 57.445291228793565, -2.7745362372626956 57.44582664833917, -2.7705728127313782 57.4444625253257, -2.771202995804206 57.443445809951186, -2.7699116534419748 57.443040491084346, -2.7685737100390986 57.44292511562011, -2.7697258493961434 57.44212167572817, -2.768050684122417 57.441397587043845, -2.7688820774854763 57.440847038060404, -2.771494180569271 57.441088659346505, -2.771512045631936 57.44195689370488, -2.7722802983500796 57.442388210442395, -2.773136809664344 57.441134331608275, -2.7780714958267274 57.44130158530779, -2.7794532390729474 57.442038630285005, -2.7772008866442994 57.44345386930809, -2.776951118335432 57.44424591617646, -2.7771013417830135 57.44504447062237, -2.7767754016250623 57.44538783121316, -2.7779471969674274 57.445908727792755, -2.7785902001831357 57.44558836937972, -2.7798402010656815 57.446022259698445, -2.7807627772681887 57.44518954319113, -2.7828308627971916 57.44573662944299, -2.783996425077801 57.44570243544188, -2.7838565788508385 57.446556297640974, -2.7826404927852755 57.44665234605826, -2.783008673528631 57.447819564848935, -2.7846672703445634 57.448551491267075, -2.783540810431262 57.44982668208935, -2.7820246177693235 57.44943685246075, -2.779934499022232 57.451341966543495, -2.7768123251074326 57.450494413775324, -2.776788087464238 57.44991804829462, -2.7773368416366653 57.449076351849875, -2.774926096296395 57.4485432389282)) |
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>