Query the Data Commons Knowledge Graph using SPARQL

Returns the results of running a graph query on the Data Commons knowledge graph using SPARQL.

URL: /query

Method: POST

Auth required: Optional

Required Arguments:

  • sparql: A Sparql query string.

This API only supports a subset of SPARQL keywords including:

  • ORDER BY
  • DISTINCT
  • LIMIT

In the query, each variable should have a typeOf condition, e.g. "?var typeOf City .".

Optional Arguments:

  • key: Your API key.

POST Request

Example

curl -X POST 'https://api.datacommons.org/query' \
-d '{"sparql": "SELECT ?name \
                WHERE { \
                  ?state typeOf State . \
                  ?state dcid geoId/06 . \
                  ?state name ?name \
                }"}'

Success Response

Code: 200 OK

Response content example

{
  "header": [
    "?name"
  ],
  "rows": [
    {
      "cells": [
        {
          "value": "California"
        }
      ]
    }
  ]
}

The response contains two fields: header and rows:

  • The value of header is an array of strings corresponding to the query variable.
  • The value of rows is an array of row object, with each containing a cells object of an array of cell.
  • The cell object has a string field value corresponds to the queried variable.

Error Response

Code: 500 Internal Server Error

Request example:

sparql parameter not specified:

curl -X POST 'https://api.datacommons.org/query'

Response content example

{
  "code": 2,
  "message": "missing required arguments"
}

Code: 401 Unauthorized

Request example: (API key not specified)

curl -X POST 'https://api.datacommons.org/query'

Response content example

{
  "code": 16,
  "message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API."
}