+https://api.datacommons.org/VERSION ++ +The current version is `v2`. + +To access a particular endpoint, append the URI to the base URL (e.g. `https://api.datacommons.org/v2/node` ). +The URIs for the V2 API are below: | API | URI path | Description | | --- | --- | ----------- | | Node | [/v2/node](/api/rest/v2/node) | Fetches information about edges and neighboring nodes | | Observation | [/v2/observation](/api/rest/v2/observation) | Fetches statistical observations | -| Resolve Entities | [/v2/resolve](/api/rest/v2/resolve) | Returns a Data Commons ID ([`DCID`](/glossary.html#dcid)) for entities in the graph | +| Resolve entities | [/v2/resolve](/api/rest/v2/resolve) | Returns a Data Commons ID ([`DCID`](/glossary.html#dcid)) for entities in the graph | +| SPARQL | [/v2/sparql](/api/rest/v2/sparql) | Returns matches to a [SPARQL](https://www.w3.org/TR/rdf-sparql-query/) graph query | + +### Parameters + +Endpoints take a set of parameters which allow you to specify the entities, variables, timescales, etc. you are interested in. The V2 APIs only use query parameters. + +### Query parameters + +Query parameters are chained at the end of a URL behind a `?` symbol. Separate multiple parameter entries with an `&` symbol. For example, this would look like: + +
+https://api.datacommons.org/v2/node?key=API_KEY&nodes=DCID1&nodes=DCID2&property=<-* ++ +Still confused? Each endpoint's documentation page has examples at the bottom tailored to the endpoint you're trying to use. + +### POST requests + +All V2 endpoints allow for `POST` requests. For `POST` requests, feed all parameters in JSON format. For example, in cURL, this would look like: + +
+curl -X POST \
+-H "X-API-Key: API_KEY" \
+--url https://api.datacommons.org/v2/node \
+--data '{
+ "nodes": [
+ "geoId/06085",
+ "geoId/06086"
+ ],
+ "property": "->[name, latitude, longitude]"
+}'
+
+
+### Find available entities, variables, and their DCIDs
+
+Most requests require the [DCID](/glossary.html#dcid) of the entity or variable you wish to query. Curious what entities and variables are available? Want to find a DCID? Take a look at our explorer tools:
+
+- [Search](https://datacommons.org/search) Search Data Commons
+- [Knowledge Graph](https://datacommons.org/browser/) Click through nodes in the knowledge graph
+- [Place Browser](https://datacommons.org/place) Summaries of data available for entities that are geographic locations
+- [Statistical Variable Explorer](https://datacommons.org/tools/statvar) See metadata for variables
+
+
+### Find date-times for observations
+
+Many endpoints allow the user to filter their results to specific dates. When querying for data at a specific date, the string passed for the date queried must match the date format (in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)) used by the target variable. An easy way to see what date format a variable uses is to look up your variable of interest in the [Statistical Variable Explorer](https://datacommons.org/tools/statvar).
+
+{: #authentication}
+## Authentication
+
+API keys are required in any REST API request. To include an API key, add your API key to the URL as a query parameter by appending ?key=API_KEY.
+
+For GET requests, this looks like:
++https://api.datacommons.org/v2/ENDPOINT?key=API_KEY ++ +If the key is not the first query parameter, use
&key=API_KEY instead. This looks like:
+
++https://api.datacommons.org/v2/ENDPOINT?QUERY=VALUE&key=API_KEY ++ +For POST requests, pass the key as a header. For example, in cURL, this looks like: + +
+curl -X POST \
+--url https://api.datacommons.org/v2/node \
+--header 'X-API-Key: API_KEY' \
+--data '{
+ "nodes": [
+ "ENTITY_DCID1",
+ "ENTITY_DCID2",
+ ...
+ ],
+ "property: "RELATION_EXPRESSION"
+}'
+
+
+{: #get-key}
+### Get API keys
+
+We provide a trial API key for general public use. This key will let you try the API and make single requests.
+
+{PROPERTY:VALUE} | Filtering; identifies the property and associated value |
| `[]` | Multiple properties, separated by commas |
| `*` | All properties linked to this node |
| `+` | One or more expressions chained together for indirect relationships, like `containedInPlace+{typeOf:City}` |
-### In and out arcs: `<-` & `->`
+### In and out arcs
-Note that arcs in the Data Commons Graph have directions. In the case of the [Argentina](https://datacommons.org/browser/country/ARG), the property `containedInPlace` exists in both `in` and `out` directions, illustrated in Figure 1:
+Arcs in the Data Commons Graph have directions. In the case of the [Argentina](https://datacommons.org/browser/country/ARG), the property `containedInPlace` exists in both `in` and `out` directions, illustrated in the following figure:
-*Figure 1. Relationship diagram for the property `containedInPlace` of the country Argentina. Note the directionality of the property `containedInPlace`: for the node "Argentina", the `in` arc represents "Argentina contains Buenos Aires", while the `out` arc represents "Argentina in South America".*
-
+Note the directionality of the property `containedInPlace`: for the node "Argentina", the `in` arc represents "Argentina contains Buenos Aires", while the `out` arc represents "Argentina in South America".*
-For example, nodes from `out` arcs are represented by `->`, while nodes from
+Nodes from `out` arcs are represented by `->`, while nodes from
`in` arcs are represented by `<-`. To illustrate using the above example:
-- Regions that include Argentina (dcid: `country/ARG`): `country/ARG->containedInPlace`
-- All cities directly contained in Argentina (dcid: `country/ARG`): `country/ARG<-containedInPlace{typeOf:City}`
+- Regions that include Argentina (DCID: `country/ARG`): `country/ARG->containedInPlace`
+- All cities directly contained in Argentina (DCID: `country/ARG`): `country/ARG<-containedInPlace{typeOf:City}`
-### Filters: `{property:value}`
+### Filters
-Filters can be used to reduce results to only match nodes with a specified property and value. Using the same example, `country/ARG<-containedInPlace+{typeOf:City}` will only return nodes with the `typeOf:City`, filtering out `typeOf:AdministrativeArea1` and so on.
+You can use filters to reduce results to only match nodes with a specified property and value. Use {} to specify property:value pairs to define the filter. Using the same example, `country/ARG<-containedInPlace+{typeOf:City}` only returns nodes with the `typeOf:City`, filtering out `typeOf:AdministrativeArea1` and so on.
-### Specifying multiple properties: `[property1, property2]`
+### Specify multiple properties
-Multiple properties can be combined together within `[]`. For example, in order to request a few `out` arcs for a node, use
-`->[name, latitude, longitude]` (this example is [fully described in this Node API example](/api/rest/v2/node.html#multiple-properties)).
+You can combine multiple properties together within `[]`. For example, in order to request a few `out` arcs for a node, use
+`->[name, latitude, longitude]` (this example is fully described in this [Node API example](/api/rest/v2/node.html#multiple-properties)).
-### Wildcard: `*`
+### Wildcard
-In order to retrieve all properties linked to a node, use the `*`, e.g. `<-*`.
-This example is [fully described in this Node API example](/api/rest/v2/node.html#wildcard).
+To retrieve all properties linked to a node, use the `*`, e.g. `<-*`.
+This example is fully described in this [Node API example](/api/rest/v2/node.html#wildcard).
-### Chaining properties: `+`
+### Chain properties
A property chain expression represents requests for information about nodes
-which are connected by the same property, but are a few hops away. This is supported only for the `containedInPlace` property.
-
-To illustrate again using the Argentina example:
-- All cities directly contained in Argentina (dcid: `country/ARG`): `country/ARG<-containedInPlace{typeOf:City}`
-- All cities indirectly contained in Argentina (dcid: `country/ARG`): `country/ARG<-containedInPlace+{typeOf:City}`
\ No newline at end of file
+which are connected by the same property, but are a few hops away. This is supported only for the `containedInPlace` property.
\ No newline at end of file
diff --git a/api/rest/v2/node.md b/api/rest/v2/node.md
index 8f3dba300..ac2dc0680 100644
--- a/api/rest/v2/node.md
+++ b/api/rest/v2/node.md
@@ -1,33 +1,29 @@
---
layout: default
title: Node
-nav_order: 1
+nav_order: 3
parent: REST (v2)
grand_parent: API
published: true
-permalink: /api/rest/v2/node
---
# /v2/node
-Fetches node information for edges and neighboring nodes. This is useful for
+The Node API fetches node information for edges and neighboring nodes. This is useful for
finding local connections between nodes of the Data Commons knowledge graph.
More specifically, this API can perform the following tasks:
-
- Get all property labels associated with individual or multiple nodes.
- Get the values of a property for individual or multiple nodes. These can also
be chained for multiple degrees in the graph.
- Get all connected nodes that are linked with invidiual or mutiple nodes.
-
Data Commons represents node relations as directed edges between nodes, or
property. The name of the property is label, while the target node is a value of
the property. This endpoint returns the property labels and values that are
connected to the queried node.
-
The REST (v2) API introduces [relation
expressions](/api/rest/v2/#relation-expressions) in the API syntax to represent
neighboring nodes, and to support chaining and filtering. For more information
-see [Data Commons REST (v2) API Overview](/api/rest/v2/#relation-expressions).
+see [Data Commons REST (v2) API overview](/api/rest/v2/index.html#relation-expressions).
{
"data": {
- "{node_DCID}": {
+ "NODE_DCID": {
"arcs": {
- "{label}": {
+ "LABEL": {
"nodes": [
...
]
@@ -105,25 +96,25 @@ The response looks like:
...
},
"properties": [
- "{value}",
+ "VALUE",
],
}
}
- "nextToken": "{token_string}"
+ "nextToken": "TOKEN_STRING"
}
-```
+
### Response fields
| Name | Type | Description |
| --------- | ------ | ---------------------------------------------------------------------------- |
| data | object | Data of the property label and value information, keyed by the queried nodes |
-| nextToken | string | [Pagination] A token used to query next page of data |
+| nextToken | string | A token used to query [next page of data](index.md#pagination) |
{: .doc-table}
## Examples
-### Example 1: All "in" Properties for a Given Node
+### Example 1: Get all "in" properties for a given node
Get the properties of the node with DCID `geoId/06` by querying all in
properties with the `<-` symbol.
@@ -139,7 +130,7 @@ property: "<-"
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-'
```
@@ -164,10 +155,9 @@ Response:
```
{: .example-box-content .scroll}
-### Example 2: Get One Property for a Given Node
+### Example 2: Get one property for a given node
-Get a `name` property for a given node with DCID `dc/03lw9rhpendw5` by querying the
-`->name` symbol.
+Get a `name` property for a given node with DCID `dc/03lw9rhpendw5` by querying the `->name` symbol.
Parameters:
{: .example-box-title}
@@ -180,7 +170,7 @@ property: "->name"
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=dc/03lw9rhpendw5&property=->name'
```
@@ -210,7 +200,7 @@ Response:
{: #multiple-properties}
-### Example 3: Get Multiple Property Values for Multiple Nodes
+### Example 3: Get multiple property values for multiple nodes
Get `name`, `latitude`, and `longitude` value for several nodes: `geoId/06085`
and `geoId/06086`. Note that multiple properties for a given node must be
@@ -227,7 +217,7 @@ property: "->[name, latitude, longitude]"
Request:
{: .example-box-title}
-```bash
+```
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/node \
-d '{"nodes": ["geoId/06085", "geoId/06086"], "property": "->[name, latitude, longitude]"}'
@@ -296,7 +286,7 @@ Response:
{: #wildcard}
-### Example 4: All "In" Triples for a Node
+### Example 4: Get all "in" triples for a node
Get all the `in` triples for node `PowerPlant` with property `<-*`.
@@ -311,7 +301,7 @@ property: "<-*"
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=PowerPlant&property=<-*'
```
@@ -340,7 +330,7 @@ Response:
},
},
},
- "nextToken": "{token_string}"
+ "nextToken": "..."
}
```
{: .example-box-content .scroll}
\ No newline at end of file
diff --git a/api/rest/v2/observation.md b/api/rest/v2/observation.md
index e0454fbe6..efbbc9e36 100644
--- a/api/rest/v2/observation.md
+++ b/api/rest/v2/observation.md
@@ -10,30 +10,63 @@ permalink: /api/rest/v2/observation
# /v2/observation
-This API fetches statistical observations. An observation is associated with an
-entity and variable at a particular date. For example, “population of USA in
+The Observation API fetches statistical observations. An observation is associated with an
+entity and variable at a particular date: for example, “population of USA in
2020”, “GDP of California in 2010”, “predicted temperature of New York in 2050”,
and so on.
-When querying observations, you need to provide variables, entities, and date.
-Variables are specified as a list in the form of
+When querying observations, you need to provide variable, entities, and dates.
+Specify variables as a list, in this form:
-```json
+yaml
+```yaml
{
- "dcids": ["
{
- "dcids": ["", "ENTITY_DCID1", "ENTITY_DCID2"]
}
- ```
+
- Node expression:
@@ -43,11 +76,11 @@ follows:
}
```
-Date is specified in the following values:
+You must specify dates using any of the following values:
-- **LATEST**: to fetch the latest observations.
-- **{date_string}**: like "2020", "2010-12".
-- **""**: date is not specified and observations are returned for all dates.
+- `LATEST`: Fetch the latest observations only.
+- DATE_STRING: Fetch observations matching the specified date(s). The date string must be in the format _YYYY_, _YYYY-MM_, or _YYYY-MM-DD_, like `2020`, `2010-12`
+- `""`: Return observations for all dates.
The response for an observation is a multi-level object generic response that
can handle all the cases mentioned above. The observation request is first
@@ -60,25 +93,25 @@ are collected and ordered based on preferences.
Keep in mind the following rules when querying observations:
- Each facet contains a list of observations.
-- Each observation has a “date” and “value”.
+- Each observation has a "date" and "value".
- The response may not have all levels and all fields, depending on the query
parameters listed in the next bullet.
-- There is a request parameter named "select" that is used to indicate the
- values the response should contain. Below are the scenarios:
- - `select = [“variable”, “entity”, “date”, “value”];` the response contains
- actual observation with date and value for each variable and entity.
- - `select = [“variable”, “entity”];` the response does not return an actual
- observation because the date and value are not queried. This can be used to
- check data existence for "variable", "entity" pairs and to fetch all the
+- There is a request parameter named "select" that you can use to indicate the
+ values the response should contain. Below are the possible expressions:
+ - `select = ["variable", "entity", "date", "value"];` the response contains
+ actual observations with the date and value for each variable and entity.
+ - `select = ["variable", "entity"];` the response does not return an actual
+ observation because the date and value are not queried. You can use this to
+ check the existence of variable-entity pairs in the data and fetch all the
variables that have data for given entities.
See the examples below for use cases that use the preceding rules.
## Examples
-### Example 1: Latest observation for given entities
+### Example 1: Get the latest observation for given entities
-Specify `date=LATEST` in order to get the latest observations and values. In this example, we are selecting the entity by its DCID using `entity.dcids`.
+Specify `date=LATEST` in order to get the latest observations and values. In this example, we select the entity by its DCID using `entity.dcids`.
Parameters:
{: .example-box-title}
@@ -96,7 +129,7 @@ variable.dcids: "Count_Person"
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=LATEST&entity.dcids=country%2FUSA&select=entity&select=variable&select=value&select=date&variable.dcids=Count_Person'
```
@@ -153,13 +186,13 @@ Response:
```
{: .example-box-content .scroll}
-### Example 2: Observation at a particular date for given entities
+### Example 2: Get the observations at a particular date for given entities
-This queries for observations in "2015" of the variable
-[Count_Person](https://datacommons.org/tools/statvar#sv=Count_Person)
+This queries for observations in 2015 for the variable
+[`Count_Person`](https://datacommons.org/tools/statvar#sv=Count_Person)
for two specified entities:
-["country/USA"](https://datacommons.org/browser/country/USA) and
-["geoId/06"](https://datacommons.org/browser/geoId/06).
+[`country/USA`](https://datacommons.org/browser/country/USA) and
+[`geoId/06`](https://datacommons.org/browser/geoId/06).
Parameters:
{: .example-box-title}
@@ -178,7 +211,7 @@ variable.dcids: "Count_Person"
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=2015&entity.dcids=country%2FUSA&entity.dcids=geoId%2F06&select=date&select=entity&select=value&select=variable&variable.dcids=Count_Person'
```
@@ -235,14 +268,14 @@ Response:
```
{: .example-box-content .scroll}
-### Example 3: Latest observation for all California counties
+### Example 3: Get the latest observations for all California counties
In this example, we use the [chained property
(`+`)](/api/rest/v2/#relation-expressions) to specify "all contained places in
[California](https://datacommons.org/browser/geoId/06) (dcid: `geoId/06`) of
type `County`". Then we specify the select fields to request actual observations
with date and value for each variable
-([Count_Person](https://datacommons.org/tools/statvar#sv=Count_Person)) and
+([`Count_Person`](https://datacommons.org/tools/statvar#sv=Count_Person)) and
entity (all counties in California).
Parameters:
@@ -261,7 +294,7 @@ variable.dcids: "Count_Person"
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=2015&date=LATEST&entity.expression=geoId%2F06%3C-containedInPlace%2B%7BtypeOf%3ACounty%7D&select=date&select=entity&select=value&select=variable&variable.dcids=Count_Person'
```
diff --git a/api/rest/v2/resolve.md b/api/rest/v2/resolve.md
index 050f3866c..fb92b006f 100644
--- a/api/rest/v2/resolve.md
+++ b/api/rest/v2/resolve.md
@@ -1,21 +1,19 @@
---
layout: default
-title: Resolve Entities
-nav_order: 3
+title: Resolve entities
+nav_order: 4
parent: REST (v2)
grand_parent: API
published: true
-permalink: /api/rest/v2/resolve
---
# /v2/resolve
-Returns a Data Commons ID ([`DCID`](/glossary.html#dcid)) for entities in the graph.
-
+The Resolve API returns a Data Commons ID ([`DCID`](/glossary.html#dcid)) for entities in the graph.
Each entity in Data Commons has an associated `DCID` which is used to refer to it
in other API calls or programs. An important step for a Data Commons user is to
identify the DCIDs of entities they care about. This API searches for an entry in the
-Data Commons knowledge graph and returns the DCIDs of matches. Users can use
+Data Commons knowledge graph and returns the DCIDs of matches. You can use
common properties or even descriptive words to find entities.
For example, you could query for "San Francisco, CA" or "San Francisco" to find
@@ -25,8 +23,8 @@ the US state).
The REST (v2) API introduces [relation
expressions](/api/rest/v2/#relation-expressions) in the API syntax to represent
-node relations, support chaining and filtering. For more information
-see [Data Commons REST (v2) API Overview](/api/rest/v2/#relation-expressions).
+node relations and support chaining and filtering. For more information
+see the [REST (v2) API overview](/api/rest/v2/index.html#relation-expressions).
{
"entities": [
{
- "node": "{NODE_1}",
+ "node": "NODE}",
"candidates": [
{
- "dcid": "{DCID 1}",
- "dominantType": "{type of DCID 1}"
+ "dcid": "DCID1}",
+ "dominantType": "TYPE_OF_DCID1"
},
]
},
{
- "node": "{NODE_2}",
+ "node": "NODE2",
"candidates": [
{
- "dcid": "{DCID 2}",
- "dominantType": "{type of DCID 2}"
+ "dcid": "DCID2",
+ "dominantType": "TYPE_OF_DCID2"
},
]
},
...
]
}
-```
+
{: .response-signature .scroll}
### Response fields
-| Name | Type | Description |
-| ----------- | ------ | ------------------------------------------------------------------------------------------------------ |
+| Name | Type | Description |
+|-------------|--------|-------------------------------------|
| node | string | The property value or description provided. |
| candidates | list | DCIDs matching the description you provided, along with an optional `dominantType` field which can be used for filtering multiple results. |
{: .doc-table}
@@ -148,11 +147,10 @@ Parameters:
nodes: "Q30"
property: "<-wikidataId->dcid"
```
-
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Q30&property=<-wikidataId->dcid'
```
@@ -177,9 +175,9 @@ Response:
### Example 2: Find the DCID of a place by coordinates
-This queries for the DCID of "_Mountain View_" by its coordinates. This is most often represented by the [`latitude`](https://datacommons.org/browser/latitude) and [`longitude`](https://datacommons.org/browser/longitude) properties on a node. Since the API only supports querying a single property, we use the synthetic `geoCoordinate` property. To specify the latitude and longitude, use the `#` sign to separate both values. This returns all the places in the graph that contains the coordinate.
+This queries for the DCID of "Mountain View" by its coordinates. This is most often represented by the [`latitude`](https://datacommons.org/browser/latitude) and [`longitude`](https://datacommons.org/browser/longitude) properties on a node. Since the API only supports querying a single property, use the synthetic `geoCoordinate` property. To specify the latitude and longitude, use the `#` sign to separate both values. This returns all the places in the graph that contains the coordinate.
-Note: If using GET, the `#` should be escaped to `%23`.
+Note: If using GET, escape `#` to `%23`.
Parameters:
{: .example-box-title}
@@ -188,14 +186,14 @@ Parameters:
nodes: "37.42#-122.08"
property: "<-geoCoordinate->dcid"
```
-
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=37.42%23-122.08&property=<-geoCoordinate->dcid'
```
+
{: .example-box-content .scroll}
Response:
@@ -260,7 +258,7 @@ Response:
### Example 3: Find the DCID of a place by name
-This queries for the DCID of "_Georgia_". Notice that specifying "_Georgia_" without specifying `type` returns all possible DCIDs with the same name: the state of Georgia in USA ([geoId/13](https://datacommons.org/browser/geoId/13)), the country Georgia ([country/GEO](https://datacommons.org/browser/country/GEO)) and the city Georgia in the US state of Vermont ([geoId/5027700](https://datacommons.org/browser/geoId/5027700)).
+This queries for the DCID of "Georgia". Notice that specifying "_Georgia_" without specifying `type` returns all possible DCIDs with the same name: the state of Georgia in USA ([geoId/13](https://datacommons.org/browser/geoId/13)), the country Georgia ([country/GEO](https://datacommons.org/browser/country/GEO)) and the city Georgia in the US state of Vermont ([geoId/5027700](https://datacommons.org/browser/geoId/5027700)).
Note that we use the `description` property in the request. This currently only supports resolving place entities by name.
@@ -275,7 +273,7 @@ property: "<-description->dcid"
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia&property=<-description->dcid
```
@@ -300,9 +298,9 @@ Response:
```
{: .example-box-content .scroll}
-### Example 4: Find the DCID of a place by name, specifying type
+### Example 4: Find the DCID of a place by name, with a type filter
-This queries for the DCID of "_Georgia_". Unlike in the previous example, here
+This queries for the DCID of "Georgia". Unlike in the previous example, here
we also specify its type using a filter and only get one place in the response.
Parameters:
@@ -312,11 +310,10 @@ Parameters:
nodes: "Georgia"
property: "<-description{typeOf:State}->dcid"
```
-
Request:
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia&property=<-description{typeOf:State}->dcid
```
@@ -341,7 +338,7 @@ Response:
### Example 5: Find the DCID of multiple places by name, with a type filter
-This queries for the DCID of "_Mountain View_" and "_New York City_".
+This queries for the DCIDs of "Mountain View" and "New York City".
Parameters:
{: .example-box-title}
@@ -350,11 +347,10 @@ Parameters:
nodes: "Mountain View, CA", "New York City"
property: "<-description{typeOf:City}->dcid"
```
-
Request (GET):
{: .example-box-title}
-```bash
+```
curl --request GET --url \
'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes%3DMountain%20View%2C%20CA&nodes=New%20York%20City&property=%3C-description%7BtypeOf%3ACity%7D-%3Edcid'
```
@@ -363,7 +359,7 @@ curl --request GET --url \
Request (POST):
{: .example-box-title}
-```bash
+```
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/resolve \
-d '{"nodes": ["Mountain View, CA", "New York City"], "property": "<-description{typeOf:City}->dcid"}'
@@ -391,5 +387,4 @@ Response:
}
]
}
-```
-{: .example-box-content .scroll}
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/api/rest/v2/sparql.md b/api/rest/v2/sparql.md
new file mode 100644
index 000000000..5a7bf580b
--- /dev/null
+++ b/api/rest/v2/sparql.md
@@ -0,0 +1,182 @@
+---
+layout: default
+title: SPARQL
+nav_order: 5
+parent: REST (v2)
+grand_parent: API
+published: true
+---
+
+# /v2/sparql
+
+This endpoint makes it possible to query the Data Commons knowledge graph using
+[SPARQL](https://www.w3.org/TR/rdf-sparql-query/). 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
+
+?VARIABLE_NAME typeOf City. |
+{: .doc-table }
+
+## Response
+
+The response looks like:
+
+
+{
+ "header": [
+ STRING
+ ],
+ "rows": [
+ {
+ "cells": [
+ {
+ "value": STRING
+ }
+ ]
+ },
+ ...
+ ]
+}
+
+{: .response-signature .scroll}
+
+### 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. |
+{: .doc-table}
+
+## 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:
+{: .example-box-title}
+
+```
+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"
+}'
+```
+{: .example-box-content .scroll}
+
+Response:
+{: .example-box-title}
+
+```json
+{
+ "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"
+ }
+ ]
+ }
+ ]
+}
+```
+{: .example-box-content .scroll}
\ No newline at end of file
diff --git a/api/rest/v2/troubleshooting.md b/api/rest/v2/troubleshooting.md
new file mode 100644
index 000000000..2b6cacaa4
--- /dev/null
+++ b/api/rest/v2/troubleshooting.md
@@ -0,0 +1,91 @@
+---
+layout: default
+title: Troubleshooting
+nav_order: 6
+parent: REST (v2)
+grand_parent: API
+published: true
+---
+
+# Troubleshoot common error responses
+
+## "Method does not exist"
+
+```json
+{
+ "code": 5,
+ "message": "Method does not exist.",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.DebugInfo",
+ "stackEntries": [],
+ "detail": "service_control"
+ }
+ ]
+}
+```
+
+This is most commonly seen when the endpoint is misspelled or otherwise malformed. Check the spelling of your endpoint and that all required path parameters are provided in the right order.
+
+## Missing API key
+
+```json
+{
+ "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.",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.DebugInfo",
+ "stackEntries": [],
+ "detail": "service_control"
+ }
+ ]
+}
+```
+
+This is seen when your request is missing an API key. Please [request your own API key](/api/index.html#get-key).
+
+
+## "Invalid request URI"
+
+```json
+{
+ "code": 3,
+ "message": "Invalid request URI",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.DebugInfo",
+ "stackEntries": [],
+ "detail": "internal"
+ }
+ ]
+}
+```
+
+This is most commonly seen when your request is missing a required path parameter. Make sure endpoints and parameters are both spelled correctly and provided in the right order.
+
+## Empty response
+
+```json
+{}
+```
+
+Sometimes your query might return an empty result. This is most commonly seen when the value provided for a parameter is misspelled or doesn't exist. Make sure the values you are passing for parameters are spelled correctly.
+
+## Marshaling errors
+
+```json
+{
+ "code": 13,
+ "message": "grpc: error while marshaling: proto: Marshal called with nil",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.DebugInfo",
+ "stackEntries": [],
+ "detail": "internal"
+ }
+ ]
+}
+```
+
+This is most commonly seen when a query parameter is missing, misspelled or incorrect. Check the spelling of query parameters and ensure all required parameters are sent in the request.
\ No newline at end of file