/v1/query

Query the Data Commons knowledge graph using 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 to an end user.

Request

POST Request

URL: https://api.datacommons.org/v1/query Header: X-API-Key: {your_api_key} JSON Data: { "sparql": "your SPARQL query here" }

Path Parameters

There are no path parameters for this endpoint.

Query Parameters

Name Type Description
key
Required
string Your API key. See the page on authentication for a demo key, as well as instructions on how to get your own key.
sparql
Required
string A SPARQL query string.
In the query, each variable should have a typeOf condition (e.g. ?var 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: Query the Data Commons knowledge graph with SPARQL

Retrieve a list of 10 biological specimens (DCID: BiologicalSpecimen) in reverse alphabetical order.

Request:

curl --request POST \
  --url https://api.datacommons.org/v1/query \
  --header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
  --data '{
            "sparql": "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 27, 2024 • Send feedback about this page