/v2/node
Data Commons represents node relations as directed edges between nodes, or properties. The name of the property is a label, while the target node is the value of the property. The Node API returns the property labels and values that are connected to the queried node. 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 hops in the graph.
- Get all connected nodes that are linked with individual or multiple nodes.
Request
Query parameters
Name | Type | Description |
---|---|---|
key |
string | Your API key. See the section on authentication for details. |
nodes |
list of strings | List of the DCIDs of the nodes to query. |
property |
string | Property to query, represented with symbols including arrow notation. For more details, see relation expressions. By using different property parameters, you can query node information in different ways, such as getting the edges and neighboring node values. Examples below show how to request this information for one or multiple nodes. |
Response
The response looks like:
{ "data": { "NODE_DCID": { "arcs": { "LABEL": { "nodes": [ ... ] } ... }, "properties": [ "VALUE", ], } } "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 | A token used to query next page of data |
Examples
Example 1: Get all incoming arcs for a given node
Get all incoming arcs of the node with DCID geoId/06
by querying all properties with the <-
symbol. This returns just the property labels.
Parameters:
nodes: "geoId/06"
property: "<-"
Request:
curl --request GET --url \
'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-'
Response:
{
"data": {
"geoId/06": {
"properties": [
"affectedPlace",
"containedInPlace",
"location",
"member",
"overlapsWith"
]
}
}
}
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.
Parameters:
nodes: "dc/03lw9rhpendw5"
property: "->name"
Request:
curl --request GET --url \
'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=dc/03lw9rhpendw5&property=->name'
Response:
{
"data": {
"dc/03lw9rhpendw5": {
"arcs": {
"name": {
"nodes": [
{
"provenanceId": "dc/base/EIA_860",
"value": "191 Peachtree Tower"
}
]
}
}
}
}
}
Example 3: Get multiple property values for multiple nodes
Get name
, latitude
, and longitude
values for several nodes: geoId/06085
and geoId/06087
. Note that multiple properties for a given node must be
enclosed in square brackets []
.
Parameters:
nodes: "geoId/06085", "geoId/06087"
property: "->[name, latitude, longitude]"
Request:
curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/node \
-d '{"nodes": ["geoId/06085", "geoId/06087"], "property": "->[name, latitude, longitude]"}'
Response:
{
"data" : {
"geoId/06085" : {
"arcs" : {
"latitude" : {
"nodes" : [
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "37.221614"
},
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "37.36"
}
]
},
"longitude" : {
"nodes" : [
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "-121.68954"
},
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "-121.97"
}
]
},
"name" : {
"nodes" : [
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "Santa Clara County"
}
]
}
}
},
"geoId/06087" : {
"arcs" : {
"latitude" : {
"nodes" : [
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "37.012347"
},
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "37.03"
}
]
},
"longitude" : {
"nodes" : [
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "-122.007789"
},
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "-122.01"
}
]
},
"name" : {
"nodes" : [
{
"provenanceId" : "dc/base/WikidataOtherIdGeos",
"value" : "Santa Cruz County"
}
]
}
}
}
}
}
Example 4: Get all incoming linked nodes for a node
Get all the incoming linked nodes for node PowerPlant
, using <-*
. Note that, unlike example 1, this query returns the actual property values, not just their labels.
Parameters:
nodes: "PowerPlant"
property: "<-*"
Request:
curl --request GET --url \
'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=PowerPlant&property=<-*'
Response:
{
"data": {
"PowerPlant": {
"arcs": {
"domainIncludes": {
"nodes": [
{
"types": [
"Property"
],
"dcid": "ashImpoundmentStatus",
"provenanceId": "dc/base/BaseSchema"
},
...
}
"subClassOf" : {
"nodes" : [
{
"dcid" : "PowerPlantUnit",
"name" : "PowerPlantUnit",
"provenanceId" : "dc/base/BaseSchema",
"types" : [
"Class"
]
}
]
},
"typeOf" : {
"nodes" : [
{
"dcid" : "dc/000qxlm93vn93",
"name" : "Suzlon Project VIII LLC",
"provenanceId" : "dc/base/EIA_860",
"types" : [
"PowerPlant"
]
},
...
},
...
}
}
},
"nextToken": "H4sIAAAAAAAA/0zIMQ6CMBjFcfus9fnpYP4Xs4MXYCgTAUKaEG7PyvqLf0Rd9rbVaZh7lH6s7TdejRtyQhbyHTkjP5AL8hPZyC/kQH6T/fmmEwAA//8BAAD///dHSrJWAAAA"
}