diff --git a/.gitignore b/.gitignore index ccc29dfde..d18babbad 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,5 @@ _site/ vendor/ .bundle/ .vscode/ -.jekyll-cache \ No newline at end of file +.jekyll-cache +.jekyll-metadata \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 9a961bdc7..7831e8132 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -229,14 +229,8 @@ GEM nokogiri (1.14.3) mini_portile2 (~> 2.8.0) racc (~> 1.4) - nokogiri (1.14.3-arm64-darwin) - racc (~> 1.4) nokogiri (1.14.3-x86_64-darwin) racc (~> 1.4) - nokogiri (1.13.3-x86_64-darwin) - racc (~> 1.4) - nokogiri (1.13.3-x86_64-darwin) - racc (~> 1.4) octokit (4.21.0) faraday (>= 0.9) sawyer (~> 0.8.0, >= 0.5.3) diff --git a/api/pandas/index.md b/api/pandas/index.md index 5bd01f661..22442de9f 100644 --- a/api/pandas/index.md +++ b/api/pandas/index.md @@ -1,10 +1,11 @@ --- layout: default title: Pandas -nav_order: 3 +nav_order: 4 parent: API has_children: true --- + # Data Commons Pandas API The **Data Commons Pandas API** is a superset of the Data Commons Python API: @@ -21,8 +22,8 @@ Before proceeding, make sure you have followed the setup instructions below. To get started using the Pandas API: -* Install the API using `pip`. -* Begin developing with the Pandas API +- Install the API using `pip`. +- Begin developing with the Pandas API ### Installing the Pandas API diff --git a/api/python/index.md b/api/python/index.md index 14c98b437..cfa0f3d47 100644 --- a/api/python/index.md +++ b/api/python/index.md @@ -1,10 +1,11 @@ --- layout: default title: Python -nav_order: 2 +nav_order: 3 parent: API has_children: true --- + # Data Commons Python API The **Data Commons Python API** is a Python library that enables developers to @@ -19,8 +20,8 @@ Before proceeding, make sure you have followed the setup instructions below. To get started using the Python API: -* Install the API using `pip`. -* Begin developing with the Python API +- Install the API using `pip`. +- Begin developing with the Python API ### Installing the Python API diff --git a/api/rest/index.md b/api/rest/index.md index 0d5cee21c..97bc9fec7 100644 --- a/api/rest/index.md +++ b/api/rest/index.md @@ -1,10 +1,11 @@ --- layout: default title: REST (v0) -nav_order: 1 +nav_order: 2 parent: API has_children: true --- + # Data Commons REST API The **Data Commons REST API** is a REST library that enables developers to @@ -12,4 +13,3 @@ programmatically access nodes in the Data Commons knowledge graph. This package allows users to explore the structure of the graph, integrate statistics from the graph into data analysis applications and much more. Please see the [overview](/api) for more details on the design and structure of the API. - diff --git a/api/rest/v1/index.md b/api/rest/v1/index.md index 7a5472a3e..1f84b14d8 100644 --- a/api/rest/v1/index.md +++ b/api/rest/v1/index.md @@ -1,7 +1,7 @@ --- layout: default title: REST (v1) -nav_order: 0 +nav_order: 1 parent: API has_children: true published: true @@ -46,7 +46,7 @@ Methods for exploring the graph around a set of nodes. | Property Values | [/v1/property/values/](/api/rest/v1/property/values) | Get the value for a property of a specific node | | Property Values (linked) | [/v1/property/values/in/linked](/api/rest/v1/property/values/in/linked) | Get all places of a specific type contained in an ancestor place | | | | | -| bulk Triples | [/v1/bulk/triples](/api/rest/v1/bulk/triples) | Get neighboring nodes and edge labels for multiple nodes | +| bulk Triples | [/v1/bulk/triples](/api/rest/v1/bulk/triples) | Get neighboring nodes and edge labels for multiple nodes | | bulk Properties | [/v1/bulk/properties](/api/rest/v1/bulk/properties) | Get all properties for multiple nodes. | | bulk Property values | [/v1/bulk/property/values](/api/rest/v1/bulk/property/values) | Get property values for multiple properties and multiple nodes | | bulk Property Values (linked) | [/v1/bulk/property/values/in/linked](/api/rest/v1/bulk/property/values/in/linked) | Get all places of a specific type for mulitple ancestor places | @@ -57,14 +57,14 @@ Methods for retrieving information of certain types of nodes. | API | URI | Description | | --------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------- | -| Find Entities | [/v1/find/entities](/api/rest/v1/find/entities) | Find the DCID of an entity | +| Find Entities | [/v1/find/entities](/api/rest/v1/find/entities) | Find the DCID of an entity | | Place Info | [/v1/info/place](/api/rest/v1/info/place) | Get information about a place | | Variable Info | [/v1/info/variable](/api/rest/v1/info/variable) | Get information about a variable | | Variable Group Info | [/v1/info/variable-group](/api/rest/v1/info/variable-group) | Get information about a variable group | | | | | -| bulk Find Entities | [/v1/bulk/find/entities](/api/rest/v1/bulk/find/entities) | Find the DCID of an entity | -| bulk Place Info | [/v1/bulk/info/place](/api/rest/v1/bulk/info/place) | Get information about multiple places | -| bulk Variable Info | [/v1/bulk/info/variable](/api/rest/v1/bulk/info/variable) | Get information about multiple variables | +| bulk Find Entities | [/v1/bulk/find/entities](/api/rest/v1/bulk/find/entities) | Find the DCID of an entity | +| bulk Place Info | [/v1/bulk/info/place](/api/rest/v1/bulk/info/place) | Get information about multiple places | +| bulk Variable Info | [/v1/bulk/info/variable](/api/rest/v1/bulk/info/variable) | Get information about multiple variables | | bulk Variable Group Info | [/v1/bulk/info/variable-group](/api/rest/v1/bulk/info/variable-group) | Get information about multiple variable groups | ### Statistical Observations @@ -79,7 +79,7 @@ entities. | | | | | bulk Observation (single value) | [/v1/bulk/observations/point](/api/rest/v1/bulk/observations/point) | Get a single value from variables for multiple entities | | bulk Observation (single value, linked) | [/v1/bulk/observations/point/linked](/api/rest/v1/bulk/observations/point/linked) | Get a single value from variables for all places in an ancestor place | -| bulk Observation (series) | [/v1/bulk/observations/series](/api/rest/v1/bulk/observations/series) | Get all values from variables for multiple entities | +| bulk Observation (series) | [/v1/bulk/observations/series](/api/rest/v1/bulk/observations/series) | Get all values from variables for multiple entities | | bulk Observation (series, linked) | [/v1/bulk/observations/series/linked](/api/rest/v1/bulk/observations/series/linked) | Get all values from a variable for all places in an ancestor place | ### Statistical Variable diff --git a/api/rest/v2/index.md b/api/rest/v2/index.md new file mode 100644 index 000000000..f1b342f6b --- /dev/null +++ b/api/rest/v2/index.md @@ -0,0 +1,32 @@ +--- +layout: default +title: REST (v2) +nav_order: 0 +parent: API +has_children: true +published: false +permalink: /api/rest/v2 +--- + +# Data Commons REST API + +The Data Commons REST API is a +[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) library +that enables developers to programmatically access data in the Data Commons +knowledge graph. This package allows users to explore the structure of the +graph, integrate statistics from the graph into data analysis applications and +much more. + +## Getting Started + +[//]: <> (TODO: update this section for v2) +First time using the Data Commons API, or just need a refresher? Take a look at +our [Getting Started Guide](/api/rest/v1/getting_started). + +## Service Endpoints + +The base URL for all endpoints below is: + +```bash +https://api.datacommons.org/v2 +``` diff --git a/api/rest/v2/node.md b/api/rest/v2/node.md new file mode 100644 index 000000000..dc0c0663d --- /dev/null +++ b/api/rest/v2/node.md @@ -0,0 +1,338 @@ +--- +layout: default +title: Node +nav_order: 0 +parent: REST (v2) +grand_parent: API +published: false +permalink: /api/rest/v2/node +--- + +# /v2/node + +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 in the API syntax to represent +neighboring nodes, and to support chaining and filtering. For more information +see Data Commons REST (v2) API Overview. + +_Note: For filtering, this API currently only supports the `containedInPlace` +property to fetch multiple `Place` nodes. Support for more properties and node +types will be added in the future._ + +## Request + +
+ + +
+ +
+https://api.datacommons.org/v2/node?key={your_api_key}&nodes={DCID}&property={PROPERTY} +
+ +
+URL: +https://api.datacommons.org/v2/node + +Header: +X-API-Key: {your_api_key} + +JSON Data: +{ + "nodes": [ + "{value_1}", + "{value_2}", + ... + ], + "property": "{property_expression}" +} + +
+ + + + +### Query Parameters + +| Name | Type | Description | +| ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| key
Required | string | Your API key. See the [page on authentication](/api/rest/v1/getting_started#authentication) for a demo key, as well as instructions on how to get your own key. | +| nodes
Required | string | [DCIDs](/glossary.html#dcid) of the nodes to query. | +| property
Required | string | Property to query, represented with symbols including arrow notation. For more details, see Data Commons REST (v2) API Overview. | +{: .doc-table } + +By using different “property” parameters, you can query node information in +different ways such as getting the edges and neighboring node values. Notice +that the “property parameter” should follow the syntax section (reference). +You can also request this information for one or multiple nodes, as demonstrated +in the following examples. + +## Response + +The response looks like: + +```json +{ + "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 | [Pagination] A token used to query next page of data | +{: .doc-table} + +## Examples + +### Example 1: 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. + +Parameters: +{: .example-box-title} + +```bash +nodes: "geoId/06" +property: "<-" +``` + +Request: +{: .example-box-title} + +```bash +curl --request GET --url \ + 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-' +``` + +Response: +{: .example-box-title} + +```json +{ + "data": { + "geoId/06": { + "properties": [ + "affectedPlace", + "containedInPlace", + "location", + "member", + "overlapsWith" + ] + } + } +} +``` +{: .example-box-content .scroll} + +### 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: +{: .example-box-title} + +```bash +nodes: "dc/03lw9rhpendw5" +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' +``` + +Response: +{: .example-box-title} + +```json +{ + "data": { + "dc/03lw9rhpendw5": { + "arcs": { + "name": { + "nodes": [ + { + "provenanceId": "dc/base/EIA_860", + "value": "191 Peachtree Tower" + } + ] + } + } + } + } +} +``` +{: .example-box-content .scroll} + +### 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 +enclosed in square brackets `[]`. + +Parameters: +{: .example-box-title} + +```bash +nodes: "geoId/06085", "geoId/06086" +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]"}' +``` + +Response: +{: .example-box-title} + +```json +{ + "data": { + "geoId/06085": { + "arcs": { + "name": { + "nodes": [ + { + "provenanceId": "dc/base/WikidataOtherIdGeos", + "value": "Santa Clara County" + } + ] + }, + "latitude": { + "nodes": [ + { "provenanceId": "dc/base/WikidataOtherIdGeos", "value": "37.36" } + ] + }, + "longitude": { + "nodes": [ + { + "provenanceId": "dc/base/WikidataOtherIdGeos", + "value": "-121.68954" + } + ] + } + } + }, + "geoId/06087": { + "arcs": { + "name": { + "nodes": [ + { + "provenanceId": "dc/base/WikidataOtherIdGeos", + "value": "Santa Cruz County" + } + ] + }, + "latitude": { + "nodes": [ + { "provenanceId": "dc/base/WikidataOtherIdGeos", "value": "37.03" } + ] + }, + "longitude": { + "nodes": [ + { + "provenanceId": "dc/base/WikidataOtherIdGeos", + "value": "-122.01" + } + ] + } + } + } + } +} +``` +{: .example-box-content .scroll} + +### Example 4: "In" Triples for a Node + +Get the `in` triples for node `PowerPlant` with property `<-*`. + +Parameters: +{: .example-box-title} + +```bash +nodes: "PowerPlant" +property: "<-*" +``` + +Request: +{: .example-box-title} + +```bash +curl --request GET --url \ + 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=PowerPlant&property=<-*' +``` + +Response: +{: .example-box-title} + +```json +{ + "data": { + "PowerPlant": { + "arcs": { + "domainIncludes": { + "nodes": [ + { + "types": [ + "Property" + ], + "dcid": "ashImpoundmentStatus", + "provenanceId": "dc/base/BaseSchema" + }, + ... + ], + }, + ... + }, + }, + }, + "nextToken": "{token_string}" +} +``` +{: .example-box-content .scroll} \ No newline at end of file diff --git a/api/sheets/index.md b/api/sheets/index.md index a3f45c9f5..420e7e69f 100644 --- a/api/sheets/index.md +++ b/api/sheets/index.md @@ -1,10 +1,11 @@ --- layout: default title: Google Sheets -nav_order: 6 +nav_order: 5 parent: API has_children: true --- + # Data Commons Sheets API The **Data Commons Sheets API** is a Google Sheets add-on that enables Google Sheets