/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, and LIMIT 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 Required	string	Your API key. See the the section on authentication for details.
query Required	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"
        }
      ]
    }
  ]
}

Page last updated: November 21, 2024 • Send feedback about this page