/v2/sparql
This endpoint makes it possible to query the Data Commons knowledge graph using SPARQL. SPARQL is a query language developed to retrieve data from RDF graph content on the web. It leverages the graph structure innate in the data it queries to return specific information.
Note: Data Commons only supports a limited subset of SPARQL functionality at this time: specifically, only the keywords
WHERE
,ORDER BY
,DISTINCT
, andLIMIT
are supported.
Request
Note: GET requests are not provided because they are inconvenient to use with SPARQL.
POST request
URL: https://api.datacommons.org/v2/sparql Header: X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI JSON data: { "query": "SPARQL_QUERY" }
Query parameters
Name | Type | Description |
---|---|---|
key |
string | Your API key. See the the section on authentication for details. |
query |
string | A SPARQL query string. In the query, all desired entities must be specified; wildcards are not supported. Each node or entity should have a typeOf condition, for example, ?ENTITY_NAME typeOf City . |
Response
The response looks like:
{ "header": [ STRING ], "rows": [ { "cells": [ { "value": STRING } ] }, ... ] }
Response fields
Name | Type | Description |
---|---|---|
header | list | List of strings corresponding to the query variables. |
rows | list | List of row objects, with each containing a list of cells and its cell values. |
cells | object | Contains string field value corresponding to the queried variable. |
Examples
Example 1: Get a list of all cities with a particular property
Retrieve a list of the DCIDs of cities that have the property unDataLabel
.
Request:
curl --request POST \
--url https://api.datacommons.org/v2/sparql \
--header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
--data '{
"query": "SELECT DISTINCT ?subject \
WHERE { \
?subject unDataLabel ?object . \
?subject typeOf City
}
LIMIT 10"
}'
Response:
{
"header" : [
"?subject"
],
"rows" : [
{
"cells" : [
{
"value" : "nuts/DED12"
}
]
},
{
"cells" : [
{
"value" : "wikidataId/Q623736"
}
]
},
{
"cells" : [
{
"value" : "wikidataId/Q33986"
}
]
},
{
"cells" : [
{
"value" : "wikidataId/Q221921"
}
]
},
{
"cells" : [
{
"value" : "wikidataId/Q841241"
}
]
},
{
"cells" : [
{
"value" : "wikidataId/Q200797"
}
]
},
{
"cells" : [
{
"value" : "undata-geo/C16801100"
}
]
},
{
"cells" : [
{
"value" : "undata-geo/C07501077"
}
]
},
{
"cells" : [
{
"value" : "undata-geo/C23400001"
}
]
},
{
"cells" : [
{
"value" : "wikidataId/Q1005090"
}
]
}
]
}
Example 2: Get a list of biological specimens
Retrieve a list of 10 biological specimens (DCID: BiologicalSpecimen
) in
reverse alphabetical order.
Request:
curl --request POST \
--url https://api.datacommons.org/v2/sparql \
--header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
--data '{
"query": "SELECT ?name \
WHERE { \
?biologicalSpecimen typeOf BiologicalSpecimen . \
?biologicalSpecimen name ?name
}
ORDER BY DESC(?name)
LIMIT 10"
}'
Response:
{
"header": ["?name"],
"rows": [
{
"cells": [
{
"value": "x Triticosecale"
}
]
},
{
"cells": [
{
"value": "x Silene"
}
]
},
{
"cells": [
{
"value": "x Silene"
}
]
},
{
"cells": [
{
"value": "x Silene"
}
]
},
{
"cells": [
{
"value": "x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey"
}
]
},
{
"cells": [
{
"value": "x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey"
}
]
},
{
"cells": [
{
"value": "x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey"
}
]
},
{
"cells": [
{
"value": "x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey"
}
]
},
{
"cells": [
{
"value": "x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey"
}
]
},
{
"cells": [
{
"value": "x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey"
}
]
}
]
}