/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: December 17, 2024 • Send feedback about this page