From dd7d477fc682ab9939f63038a82c0875d512b458 Mon Sep 17 00:00:00 2001 From: Kara Moscoe Date: Thu, 27 Jun 2024 14:11:57 -0700 Subject: [PATCH 1/8] SPARQL docs for v2 API --- api/index.md | 32 ++-- api/python/query.md | 32 ++-- api/rest/v2/getting_started.md | 271 +-------------------------------- api/rest/v2/index.md | 227 +++++++++++++++++++++------ api/rest/v2/node.md | 100 +++++------- api/rest/v2/observation.md | 76 ++++----- api/rest/v2/resolve.md | 142 ++++++----------- api/rest/v2/troubleshooting.md | 95 ++++++++++++ 8 files changed, 438 insertions(+), 537 deletions(-) create mode 100644 api/rest/v2/troubleshooting.md diff --git a/api/index.md b/api/index.md index 14a3981e0..e0f93aa76 100644 --- a/api/index.md +++ b/api/index.md @@ -4,6 +4,7 @@ title: API nav_order: 20 has_children: true --- + # Overview The [Data Commons Graph](https://datacommons.org) aggregates data from many @@ -11,32 +12,23 @@ different [data sources](https://datacommons.org/datasets) into a single database. Data Commons is based on the data model used by [schema.org](https://schema.org); for more information, see [the guide to the data model](/data_model.html). -The **Data Commons API** allows developers to programmatically access the data in Data Commons. +The Data Commons APIs allow developers to programmatically access the data in Data Commons. Data Commons provides several different ways to access its API's resources: -1. A [REST API](/api/rest/v2) that can be used on the command line as well as in any language with an HTTP library. -1. A lightweight [Python](/api/python) wrapper. -1. A heavier [Pandas](/api/pandas) wrapper. -1. A convenient [Google Sheets](/api/sheets) add-on. +* A [REST API](/api/rest/v2) that can be used on the command line as well as in any language with an HTTP library. +* A lightweight [Python](/api/python) wrapper. +* A heavier [Pandas](/api/pandas) wrapper. -The endpoints can be roughly grouped into four categories. +The endpoints can be roughly grouped into four categories: -- **Local Node Exploration**: Given a set of nodes, explore the +- **Graph exploration**: Given a set of nodes, explore the graph around those nodes. -- **Domain specific APIs**: These are groups of APIs, specific to particular - domains. +- **Statistical data**: Given a set of statistical variables, dates and entities, get observations. -- **Graph Query/SPARQL**: Given a subgraph where some of the nodes are +- **Graph query/SPARQL**: Given a subgraph where some of the nodes are variables, retrieve possible matches. This corresponds to a subset of the - graph query language [SPARQL](https://www.w3.org/TR/rdf-sparql-query/). - -- **Utilities**: These are Python notebook specific APIs for helping with - Pandas DataFrames, etc. - -Most of the provided endpoints take references to nodes and properties as arguments. Every -node or property has a `Data Commons ID (DCID)`, which is used -to pass nodes as arguments to API calls. - -**Note:** The DCID of schema.org terms used in Data Commons is their schema.org ID. + graph query language [SPARQL](https://www.w3.org/TR/rdf-sparql-query/). This is useful for getting very specific observations which would require multiple API calls (e.g. "hate crimes motivated by disability status in Californian cities"). +- **Utilities**: These are Python notebook-specific APIs for helping with + Pandas DataFrames, etc. \ No newline at end of file diff --git a/api/python/query.md b/api/python/query.md index ad9b75dc2..7fdfc217b 100644 --- a/api/python/query.md +++ b/api/python/query.md @@ -12,7 +12,9 @@ Returns the results of running a graph query on the Data Commons knowledge graph using [SPARQL](https://www.w3.org/TR/rdf-sparql-query/). Note that Data Commons is only able to support a limited subsection of SPARQL functionality at this time: specifically only the keywords `ORDER BY`, `DISTINCT`, and `LIMIT`. -## General information about this method +Note: The Python SPARQL library currently only supports the [v1](/api/v1/query.html) version of the API. + +## General information about the query() method **Signature**: @@ -24,7 +26,7 @@ datacommons.query(query_string, select=None) * `query_string`: A SPARQL query string. -## How to construct a call to the query method +## How to construct a call to the query() method This method makes it possible to query the Data Commons knowledge graph using SPARQL. SPARQL is a query language developed to retrieve data from websites. It leverages the graph structure innate in the data it queries to return specific information to an end user. For more information on assembling SPARQL queries, check out [the Wikipedia page about SPARQL](https://en.wikipedia.org/wiki/SPARQL) and [the W3C specification information](https://www.w3.org/TR/sparql11-query/). @@ -49,11 +51,11 @@ A correct response will always look like this: The response contains an array of dictionaries, each corresponding to one node matching the conditions of the query. Each dictionary's keys match the variables in the query SELECT clause, and the values in the dictionaries are those associated to the given node's query-specified properties. -## Examples and error returns +## Examples and error responses -### Examples +The following examples and error responses, along with explanations and fixes for the errors, are available in this [Python notebook](https://colab.research.google.com/drive/1Jd0IDHnMdtxhsmXhL5Ib5tL0zgJud1k5?usp=sharing). -#### Example 1. Retrieve the name of the state associated with DCID geoId/06. +### Example 1: Retrieve the name of the state associated with DCID geoId/06. ```python >>> geoId06_name_query = 'SELECT ?name ?dcid WHERE { ?a typeOf Place . ?a name ?name . ?a dcid ("geoId/06" "geoId/21" "geoId/24") . ?a dcid ?dcid }' @@ -61,7 +63,7 @@ The response contains an array of dictionaries, each corresponding to one node m [{'?name': 'Kentucky', '?dcid': 'geoId/21'}, {'?name': 'California', '?dcid': 'geoId/06'}, {'?name': 'Maryland', '?dcid': 'geoId/24'}] ``` -#### Example 2. Retrieve a list of ten biological specimens in reverse alphabetical order. +### Example 2: Retrieve a list of ten biological specimens in reverse alphabetical order. ```python >>> bio_specimens_reverse_alphabetical_order_query = 'SELECT ?name WHERE { ?biologicalSpecimen typeOf BiologicalSpecimen . ?biologicalSpecimen name ?name } ORDER BY DESC(?name) LIMIT 10' @@ -69,7 +71,7 @@ The response contains an array of dictionaries, each corresponding to one node m [{'?name': 'x Triticosecale'}, {'?name': 'x Silene'}, {'?name': 'x Silene'}, {'?name': 'x Silene'}, {'?name': 'x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey'}, {'?name': 'x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey'}, {'?name': 'x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey'}, {'?name': 'x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey'}, {'?name': 'x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey'}, {'?name': 'x Pseudelymus saxicola (Scribn. & J.G.Sm.) Barkworth & D.R.Dewey'}] ``` -#### Example 3. Retrieve a list of GNI observations by country. +### Example 3: Retrieve a list of GNI observations by country. ```python >>> gni_by_country_query = 'SELECT ?observation ?place WHERE { ?observation typeOf StatVarObservation . ?observation variableMeasured Amount_EconomicActivity_GrossNationalIncome_PurchasingPowerParity_PerCapita . ?observation observationAbout ?place . ?place typeOf Country . } ORDER BY ASC (?place) LIMIT 10' @@ -77,7 +79,7 @@ The response contains an array of dictionaries, each corresponding to one node m [{'?observation': 'dc/o/syrpc3m8q34z7', '?place': 'country/ABW'}, {'?observation': 'dc/o/bqtfmc351v0f2', '?place': 'country/ABW'}, {'?observation': 'dc/o/md36fx6ty4d64', '?place': 'country/ABW'}, {'?observation': 'dc/o/bm28zvchsyf4b', '?place': 'country/ABW'}, {'?observation': 'dc/o/3nleez1feevw6', '?place': 'country/ABW'}, {'?observation': 'dc/o/x2yg38d0xecnf', '?place': 'country/ABW'}, {'?observation': 'dc/o/7swdqf6yjdyw8', '?place': 'country/ABW'}, {'?observation': 'dc/o/yqmsmbx1qskfg', '?place': 'country/ABW'}, {'?observation': 'dc/o/6hlhrz3k8p5wf', '?place': 'country/ABW'}, {'?observation': 'dc/o/txfw505ydg629', '?place': 'country/ABW'}] ``` -#### Example 4. Retrieve a sample list of observations with the unit InternationalDollar. +### Example 4: Retrieve a sample list of observations with the unit InternationalDollar. ```python >>> internationalDollar_obs_query = 'SELECT ?observation WHERE { ?observation typeOf StatVarObservation . ?observation unit InternationalDollar } LIMIT 10' @@ -85,7 +87,7 @@ The response contains an array of dictionaries, each corresponding to one node m [{'?observation': 'dc/o/s3gzszzvj34f1'}, {'?observation': 'dc/o/gd41m7qym86d4'}, {'?observation': 'dc/o/wq62twxx902p4'}, {'?observation': 'dc/o/d93kzvns8sq4c'}, {'?observation': 'dc/o/6s741lstdqrg4'}, {'?observation': 'dc/o/2kcq1xjkmrzmd'}, {'?observation': 'dc/o/ced6jejwv224f'}, {'?observation': 'dc/o/q31my0dmcryzd'}, {'?observation': 'dc/o/96frt9w0yjwxf'}, {'?observation': 'dc/o/rvjz5xn9mlg73'}] ``` -#### Example 5. Retrieve a list of ten distinct annual estimates of life expectancy, along with the year of estimation, for forty-seven-year-old Hungarians. +### Example 5: Retrieve a list of ten distinct annual estimates of life expectancy, along with the year of estimation, for forty-seven-year-old Hungarians. ```python >>> life_expectancy_query = 'SELECT DISTINCT ?LifeExpectancy ?year WHERE { ?o typeOf StatVarObservation . ?o variableMeasured LifeExpectancy_Person_47Years . ?o observationAbout country/HUN . ?o value ?LifeExpectancy . ?o observationDate ?year } ORDER BY ASC(?LifeExpectancy) LIMIT 10' @@ -93,7 +95,7 @@ The response contains an array of dictionaries, each corresponding to one node m [{'?LifeExpectancy': '26.4', '?year': '1993'}, {'?LifeExpectancy': '26.5', '?year': '1992'}, {'?LifeExpectancy': '26.7', '?year': '1990'}, {'?LifeExpectancy': '26.7', '?year': '1994'}, {'?LifeExpectancy': '26.8', '?year': '1991'}, {'?LifeExpectancy': '26.9', '?year': '1995'}, {'?LifeExpectancy': '27.2', '?year': '1996'}, {'?LifeExpectancy': '27.4', '?year': '1999'}, {'?LifeExpectancy': '27.5', '?year': '1997'}, {'?LifeExpectancy': '27.5', '?year': '1998'}] ``` -#### Example 6: Use the `select` function to filter returns based on name. +### Example 6: Use the `select` function to filter returns based on name. ```python >>> names_for_places_query = 'SELECT ?name ?dcid WHERE { ?a typeOf Place . ?a name ?name . ?a dcid ("geoId/06" "geoId/21" "geoId/24") . ?a dcid ?dcid }' @@ -105,9 +107,7 @@ The response contains an array of dictionaries, each corresponding to one node m {'?name': 'Maryland', '?dcid': 'geoId/24'} ``` -### Error returns - -#### Error return 1: Malformed SPARQL query. +### Error response 1: Malformed SPARQL query ```python >>> gni_by_country_query = 'SELECT ?observation WHERE { ?observation typeOf StatVarObservation . ?observation variableMeasured Amount_EconomicActivity_GrossNationalIncome_PurchasingPowerParity_PerCapita . ?observation observationAbout ?place . ?place typeOf Country . } ORDER BY ASC (?place) LIMIT 10' @@ -139,7 +139,7 @@ ValueError: Response error 500: b'{\n "code": 2,\n "message": "googleapi: Error 400: Unrecognized name: place; Did you mean name? at [1:802], invalidQuery",\n "details": [\n {\n "@type": "type.googleapis.com/google.rpc.DebugInfo",\n "stackEntries": [],\n "detail": "internal"\n }\n ]\n}\n' ``` -#### Error return 2: Malformed SPARQL query string. +### Error response 2: Malformed SPARQL query string ```python >>> gni_by_country_query = 'SELECT ?observation WHERE { ?observation typeOf StatVarObservation . ?observation variableMeasured Amount_EconomicActivity_GrossNationalIncome_PurchasingPowerParity_PerCapita . ?observation observationAbout ?place . ?place typeOf Country . } ORDER BY ASC (?place) LIMIT 10' @@ -172,7 +172,7 @@ b'{\n "code": 2,\n "message": "googleapi: Error 400: Unrecognized name: place; D >>> gni_by_country_query = 'SELECT ?observation WHERE { ?observation typeOf StatVarObservation . \\\\\ ?observation variableMeasured Amount_EconomicActivity_GrossNationalIncome_PurchasingPowerParity_PerCapita . ?observation observationAbout ?place . ?place typeOf Country . } ORDER BY ASC (?place) LIMIT 10' ``` -#### Error return 3: Bad selector. +### Error response 3: Bad selector ```python >>> names_for_places_query = 'SELECT ?name ?dcid WHERE { ?a typeOf Place . ?a name ?name . ?a dcid ("geoId/06" "geoId/21" "geoId/24") . ?a dcid ?dcid }' @@ -186,4 +186,4 @@ Traceback (most recent call last): KeyError: '?earthquake' ``` -These examples and errors, along with explanations and fixes for the errors, are available in this [Python notebook](https://colab.research.google.com/drive/1Jd0IDHnMdtxhsmXhL5Ib5tL0zgJud1k5?usp=sharing). + diff --git a/api/rest/v2/getting_started.md b/api/rest/v2/getting_started.md index 37fd10be3..089f0c3b5 100644 --- a/api/rest/v2/getting_started.md +++ b/api/rest/v2/getting_started.md @@ -1,273 +1,10 @@ --- -layout: default +layout: redirect title: Getting Started Guide nav_order: 0 parent: REST (v2) grand_parent: API -published: true +published: false permalink: /api/rest/v2/getting_started ---- - -# Getting Started Guide - -Welcome! Whether you're new to Data Commons or are just looking for a refresher, this guide gives an overview of what you need to know to get started using our REST API. - -Use the links below to jump to any section: - -* TOC -{:toc} - -## What is a REST API? - -Our REST API follows the [RESTful architectural style](https://en.wikipedia.org/wiki/Representational_state_transfer) to allow you to query the Data Commons Knowledge Graph via [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods). This allows you to explore the local graph and query data from specific variables and entities programatically. - -## How to Use the REST API - -Our REST API can be used with any tool or language that supports HTTP. You can make queries on the command line (e.g. using [cURL](https://curl.se/)), by scripting HTTP requests in another language like javascript, or even by entering an endpoint into your web browser! - -Following HTTP, a REST API call consists of a **request** that you provide, and a **response** from our servers with the data you requested in [JSON](https://json.org) format. The next section details how to assemble a request. - -### Assembling a Request - -#### Endpoints - -Requests are made through [API endpoints](https://en.wikipedia.org/wiki/Web_API#Endpoints). We provide endpoints for many different queries (see the list of available endpoints [here](/api/rest/v2)). - -Each endpoint can be acessed using its unique URL, which is a combination of a base URL and the endpoint's [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier). - -The base URL for all REST endpoints is: - -```bash -https://api.datacommons.org -``` - -And a URI looks like [`/v2/node`](/api/rest/v2/node). To access a particular endpoint, append the URI to the base URL (e.g. `https://api.datacommons.org/v2/node` ). - -#### Parameters - -Endpoints take a set of **parameters** which allow you to specify which 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: - -```bash -https://api.datacommons.org/v2/node?key=your_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: - -```bash -curl -X POST \ --H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \ ---url https://api.datacommons.org/v2/node \ ---data '{ - "nodes": [ - "geoId/06085", - "geoId/06086" - ], - "property": "->[name, latitude, longitude]" -}' -``` - -#### Finding 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 - -#### Finding Datetimes 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 - - - -#### Using API Keys - -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=`. - -For GET requests, this looks like: - -```bash -https://api.datacommons.org/v2/endpoint?key= -``` - -If the key is not the first query parameter, use `&key=` instead. This looks like: - -```bash -https://api.datacommons.org/v2/endpoint?query=value&key= -``` - -For POST requests, pass the key as a header. For example, in cURL, this looks like: - -```bash -curl -X POST \ ---url https://api.datacommons.org/v2/node \ ---header 'X-API-Key: ' \ ---data '{ - "nodes": [ - "entity_dcid_1", - "entity_dcid_2", - ... - ], - "property: "relation_expression" -}' -``` - -#### Getting API Keys - -We've provided a trial API key for general public use. This key will let you try the API and make single requests. - - - -The trial key is capped with a limited quota for requests. If you are planning on using our APIs more rigorously (e.g. for personal or school projects, developing applications, etc.) please request one by -[filling out this form](https://docs.google.com/forms/d/e/1FAIpQLSeVCR95YOZ56ABsPwdH1tPAjjIeVDtisLF-8oDYlOxYmNZ7LQ/viewform) and selecting "API access" to request an official key without any quota limits. We'll be happy to hear from you! - -{: #pagination} -### Pagination - -When the response to a request is too long, the returned payload is -**paginated**. Only a subset of the response is returned, along with a long string -of characters called a **token**. To get the next set of entries, repeat the -request with `nextToken` as an query parameter, with the token as its value. - -For example, the request: - -```bash -curl --request GET \ - 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-*' -``` - -will return something like: - -```json -{ - "data": { - "geoId/06": { - "arcs": < ... output truncated for brevity ...> - }, - }, - "nextToken": "SoME_veRy_L0ng_S+rIng" -} -``` - -To get the next set of entries, repeat the previous command and append the `nextToken`: - -```bash -curl --request GET \ - 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-*&nextToken=SoME_veRy_L0ng_S+rIng' -``` - -Similarly for POST requests, this would look like: - -```bash -curl -X POST \ --H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \ ---url https://api.datacommons.org/v2/node \ ---data '{ - "nodes": "geoId/06", - "property": "<-*", - "nextToken": "SoME_veRy_L0ng_S+rIng" -}' -``` - -## Troubleshooting - -### 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 use the trial key provided above, or request your own API 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. +redirect: index.html +--- \ No newline at end of file diff --git a/api/rest/v2/index.md b/api/rest/v2/index.md index 23293004a..b8dd9bded 100644 --- a/api/rest/v2/index.md +++ b/api/rest/v2/index.md @@ -1,104 +1,243 @@ --- layout: default title: REST (v2) -nav_order: 0 +nav_order: 1 parent: API has_children: true published: true -permalink: /api/rest/v2 --- -# Data Commons REST API +{:.no_toc} +# Data Commons REST API + +* TOC +{:toc} + +## Overview 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 +knowledge graph, using [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods). This allows you to explore the structure of the graph, integrate statistics from the graph into data analysis applications and much more. +You can use the REST API with any tool or language that supports HTTP. You can make queries on the command line (e.g. using [cURL](https://curl.se/)), by scripting HTTP requests in another language like Javascript, or even by entering an endpoint into your web browser! + + ## What's new in V2 -The V2 API collapses functionality from [V1 API](/api/rest/v1) into a smaller number of endpoints. We do this by introducing a syntax for "Relation Expressions", [described below](#relation-expressions). Each API endpoint can also handle both single and bulk requests. +The V2 API collapses functionality from [V1 API](/api/rest/v1) into a smaller number of endpoints, by introducing a syntax for _relation expressions_, [described below](#relation-expressions). Each API endpoint can also handle both single and bulk requests. -## Getting Started +## Assemble a request -First time using the Data Commons API, or just need a refresher? Take a look at -our [Getting Started Guide](/api/rest/v2/getting_started). +Following HTTP, a REST API call consists of a _request_ that you provide, and a _response_ from the Data Commons servers with the data you requested, in [JSON](https://json.org) format. The following sections detail how to assemble a request. -## Service Endpoints +### Service endpoints -The base URL for all endpoints below is: +You make requests through [API endpoints](https://en.wikipedia.org/wiki/Web_API#Endpoints). You access each endpoint using its unique URL, which is a combination of a base URL and the endpoint's [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier). -```bash -https://api.datacommons.org/v2 -``` +The base URL for all REST endpoints is: + +
+https://api.datacommons.org/VERSION_NUMBER
+
+ +The current _VERSION_NUMBER_ 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 -{: #relation-expressions} -## Introducing Relation Expressions +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. -Data Commons represents real world entities and data as nodes. These -nodes are connected by directed edges, or arcs, to form a knowledge graph. The -label of the arc is the name of the [property](/glossary.html#property). +### 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
+
-Relation expressions include arrow annotation and other symbols in the syntax to -represent neighboring nodes, and to support chaining and filtering. -These new expressions allow all of the functionality of the V1 API to be -expressed with fewer API endpoints in V2. All V2 API calls require relation -expressions in the `property` or `expression` parameter. +If the key is not the first query parameter, use &key=API_KEY instead. This looks like: -The following table describes symbols in the V2 API relation expressions: +
+https://api.datacommons.org/v2/endpoint?QUERY=VALUE&key=API_KEY
+
-| Symbol | Represents | +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. + + + +_The trial key is capped with a limited quota for requests._ If you are planning on using our APIs more rigorously (e.g. for personal or school projects, developing applications, etc.) please request one by +[filling out this form](https://docs.google.com/forms/d/e/1FAIpQLSeVCR95YOZ56ABsPwdH1tPAjjIeVDtisLF-8oDYlOxYmNZ7LQ/viewform) and selecting "API access" to request an official key without any quota limits. + +{: #pagination} +## Pagination + +When the response to a request is too long, the returned payload is +_paginated_. Only a subset of the response is returned, along with a long string +of characters called a _token_. To get the next set of entries, repeat the +request with `nextToken` as an query parameter, with the token as its value. + +For example, the request: + +
+curl --request GET \
+  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-*'
+
> + +will return something like: + +```json +{ + "data": { + "geoId/06": { + "arcs": < ... output truncated for brevity ...> + }, + }, + "nextToken": "SoME_veRy_L0ng_S+rIng" +} +``` + +To get the next set of entries, repeat the previous command and append the `nextToken`: + +```bash +curl --request GET \ + 'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-*&nextToken=SoME_veRy_L0ng_S+rIng' +``` + +Similarly for POST requests, this would look like: + +
+curl -X POST \
+-H "X-API-Key: API_KEY" \
+--url https://api.datacommons.org/v2/node \
+--data '{
+  "nodes": "geoId/06",
+  "property": "<-*",
+  "nextToken": "SoME_veRy_L0ng_S+rIng"
+
+ + + +{: #relation-expressions} +## Relation expressions + +Data Commons represents real world entities and data as nodes. These +nodes are connected by directed edges, or arcs, to form a knowledge graph. The + @@ -60,41 +214,40 @@ The following table describes symbols in the V2 API relation expressions: | ------ | ---------- | | `->` | An `out` arc | | `<-` | An `in` arc | -| `{property:value}` | Filtering; identifies the property and associated value | +| 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: ![](/assets/images/rest/property_value_direction_example.png) -*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}` -### 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. 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 +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. `<-*`. +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..60d47182e 100644 --- a/api/rest/v2/node.md +++ b/api/rest/v2/node.md @@ -1,33 +1,33 @@ --- layout: default title: Node -nav_order: 1 +nav_order: 2 parent: REST (v2) grand_parent: API published: true -permalink: /api/rest/v2/node --- +{:.no_toc} # /v2/node -Fetches node information for edges and neighboring nodes. This is useful for +* TOC +{:toc} + +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). - ## Request -
-https://api.datacommons.org/v2/node?key={your_api_key}&nodes={DCID}&property={PROPERTY} +https://api.datacommons.org/v2/node?key=API_KEY&nodes=DCID&property=PROPERTY
@@ -56,16 +54,16 @@ URL: https://api.datacommons.org/v2/node Header: -X-API-Key: {your_api_key} +X-API-Key: API_KEY JSON Data: { "nodes": [ - "{value_1}", - "{value_2}", + "VALUE1", + "VALUE2", ... ], - "property": "{property_expression}" + "property": "PROPERTY_EXPRESSION" }
@@ -73,31 +71,28 @@ JSON Data: -### Query Parameters +### Query parameters | Name | Type | Description | | ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| key
Required | string | Your API key. See the [page on authentication](/api/rest/v2/getting_started#authentication) for a demo key, as well as instructions on how to get your own key. | +| key
Required | string | Your API key. See the [page on authentication](/api/rest/v2/index.html#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. | +| property
Required | string | Property to query, represented with symbols including arrow notation. For more details, see the [Data Commons REST (v2) API overview](/api/rest/v2/index.html#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. | {: .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}": {
+    "NODE_DCID": {
       "arcs": {
-        "{label}": {
+        "LABEL": {
           "nodes": [
             ...
           ]
@@ -105,16 +100,15 @@ 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 |
@@ -123,30 +117,26 @@ The response looks like:
 
 ## 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.
-
 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=<-'
-```
+  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-'
+

 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "data": {
@@ -164,30 +154,25 @@ 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.
-
 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'
+  'https://api.datacommons.org/v2/node?key=
API_KEY
&nodes=dc/03lw9rhpendw5&property=->name'
 ```
-
 Response:
 {: .example-box-title}
-
 ```json
 {
   "data": {
@@ -210,32 +195,28 @@ 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
 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" \
+
+curl -X POST -H "X-API-Key: API_KEY" \
   https://api.datacommons.org/v2/node \
   -d '{"nodes": ["geoId/06085", "geoId/06086"], "property": "->[name, latitude, longitude]"}'
-```
+

 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "data": {
@@ -296,29 +277,26 @@ 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 `<-*`.
 
 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=<-*'
-```
+  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=PowerPlant&property=<-*'
+

 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "data": {
@@ -340,7 +318,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..ceae1ad5c 100644
--- a/api/rest/v2/observation.md
+++ b/api/rest/v2/observation.md
@@ -1,39 +1,43 @@
 ---
 layout: default
 title: Observation
-nav_order: 2
+nav_order: 3
 parent: REST (v2)
 grand_parent: API
 published: true
 permalink: /api/rest/v2/observation
 ---
 
+{:.no_toc}
 # /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
+* TOC
+{:toc}
+
+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.
+When querying observations, you need to provide variable, entities, and dates.
 Variables are specified as a list in the form of
 
-```json
+
 {
-  "dcids": ["", ""]
+  "dcids": ["VARIABLE_DCID1", "VARIABLE_DCID2>"]
 }
-```
+

 
-Entities should be specified as an enumerated list or node expression, as
+Specify entities as an enumerated list or node expression, as
 follows:
 
 - Enumerated list:
 
-  ```json
+  
   {
-    "dcids": ["", "ENTITY_DCID1", "ENTITY_DCID2"]
   }
-  ```
+  

 
 - Node expression:
 
@@ -43,11 +47,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`: to fetch the latest observations.
+- `DATE_STRING: in the format YYYY, YYYY-MM, or YYYY-MM-DD, like `2020`, `2010-12`.
+- `""`: a date is not specified and observations are returned 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,23 +64,23 @@ 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`.
 
@@ -96,10 +100,10 @@ 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'
-```
+'https://api.datacommons.org/v2/observation?key=API_KEY&date=LATEST&entity.dcids=country%2FUSA&select=entity&select=variable&select=value&select=date&variable.dcids=Count_Person'
+

 {: .example-box-content .scroll}
 
 Response:
@@ -153,9 +157,9 @@ 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
+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
@@ -178,10 +182,10 @@ 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'
-```
+'https://api.datacommons.org/v2/observation?key=API_KEY&date=2015&entity.dcids=country%2FUSA&entity.dcids=geoId%2F06&select=date&select=entity&select=value&select=variable&variable.dcids=Count_Person'
+

 {: .example-box-content .scroll}
 
 Response:
@@ -235,7 +239,7 @@ 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
@@ -261,10 +265,10 @@ 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'
-```
+'https://api.datacommons.org/v2/observation?key=API_KEY&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'
+

 {: .example-box-content .scroll}
 
 Response:
diff --git a/api/rest/v2/resolve.md b/api/rest/v2/resolve.md
index 050f3866c..2c05e1370 100644
--- a/api/rest/v2/resolve.md
+++ b/api/rest/v2/resolve.md
@@ -1,21 +1,23 @@
 ---
 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
 ---
 
+{:.no_toc}
 # /v2/resolve
 
-Returns a Data Commons ID ([`DCID`](/glossary.html#dcid)) for entities in the graph.
+* TOC
+{:toc}
 
+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,15 +27,12 @@ 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, supporting chaining and filtering. For more information
+see the [REST (v2) API overview](/api/rest/v2/index.html#relation-expressions).
 
 
-
+	@@ -36,90 +35,90 @@
 
-
 ## Request
-
 

   

 
 

-https://api.datacommons.org/v2/resolve?key={your_api_key}&nodes={NODE}&property={PROPERTY_EXPRESSION}
+https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=NODE_NAME&property=PROPERTY_EXPRESSION>
 

 
 

@@ -64,16 +61,16 @@ URL:
 https://api.datacommons.org/v2/resolve
 
 Header:
-X-API-Key: {your_api_key}
+X-API-Key: API_KEY
 
 JSON Data:
 {
   "nodes": [
-    "{NODE_1}",
-    "{NODE_2}",
+    "NODE1",
+    "NODE2",
     ...
   ],
-  "property": "{PROPERTY_EXPRESSION}"
+  "property": "PROPERTY_EXPRESSION"
 }
 
 

@@ -81,13 +78,13 @@ JSON Data:
 
 
 
-### Query Parameters
+### Query parameters
 
 | Name                                                  | Type   | Description                                                                                                                                                     |
 | ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| key 
 Required      | string | Your API key. See the [page on authentication](/api/rest/v2/getting_started#authentication) for a demo key, as well as instructions on how to get your own key. |
-| nodes 
 Required    | string | The queried property value (e.g. entity name or ID), or description of the node (this currently only supports the name of the place).
-| property 
 Required | string | Property expression that represents the relation of the given nodes to the queried entities. Since we are resolving to DCID, note that this should always end with `->dcid` |
+| key 
 Required      | string | Your API key. See the [page on authentication](/api/rest/v2/index.html#authentication) for a demo key, as well as instructions on how to get your own key. |
+| nodes 
 Required    | string | The queried property value (e.g. entity name or DCID), or description of the node (this currently only supports the name of a place).
+| property 
 Required | string | Property expression that represents the relation of the given nodes to the queried entities. Note that this should always end with `->dcid` |
 
 {: .doc-table }
 
@@ -95,72 +92,63 @@ JSON Data:
 
 The response looks like:
 
-```json
+
 {
   "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": "var>TYPE_OF_DCID2"
         },
       ]
     },
     ...
   ]
 }
-```
+

 {: .response-signature .scroll}
 
 ### Response fields
-
 | 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}
-
 
-
 ## Examples
-
 ### Example 1: Find the DCID of a place by another known ID
-
 This queries for the DCID of a place by its Wikidata ID. This property is represented in the graph by [`wikidataId`](https://datacommons.org/browser/wikidataId).
-
 Parameters:
 {: .example-box-title}
-
 ```bash
 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'
+'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Q30&property=<-wikidataId->dcid'
 ```
 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "entities": [
@@ -177,30 +165,27 @@ 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, 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.
 
-Note: If using GET, the `#` should be escaped to `%23`.
+Note: If using GET, escape `#` to `%23`.
 
 Parameters:
 {: .example-box-title}
-
 ```bash
 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'
+'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=37.42%23-122.08&property=<-geoCoordinate->dcid'
 ```
 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "entities": [
@@ -218,25 +203,7 @@ Response:
         {
           "dcid": "geoId/06",
           "dominantType": "State"
-        },
-        {
-          "dcid": "country/USA",
-          "dominantType": "Country"
-        },
-        {
-          "dcid": "geoId/06085504601",
-          "dominantType": "CensusTract"
-        },
-        {
-          "dcid": "geoId/060855046011",
-          "dominantType": "CensusBlockGroup"
-        },
-        {
-          "dcid": "geoId/0608592830",
-          "dominantType": "CensusCountyDivision"
-        },
-        {
-          "dcid": "geoId/0618",
+	@@ -240,27 +239,27 @@
           "dominantType": "CongressionalDistrict"
         },
         {
@@ -260,30 +227,27 @@ 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.
 
 Parameters:
 {: .example-box-title}
-
 ```bash
 nodes: "Georgia"
 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
+'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Georgia&property=<-description->dcid
 ```
 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "entities": [
@@ -297,34 +261,31 @@ Response:
     }
   ]
 }
-```
+

 {: .example-box-content .scroll}
 
 ### Example 4: Find the DCID of a place by name, specifying type
 
-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:
 {: .example-box-title}
-
 ```bash
 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
-```
+'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Georgia&property=<-description{typeOf:State}->dcid
+

 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "entities": [
@@ -341,38 +302,35 @@ 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 DCID of "Mountain View" and "New York City".
 
 Parameters:
 {: .example-box-title}
-
 ```bash
 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'
-```
+'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes%3DMountain%20View%2C%20CA&nodes=New%20York%20City&property=%3C-description%7BtypeOf%3ACity%7D-%3Edcid'
+

 {: .example-box-content .scroll}
 
 Request (POST):
 {: .example-box-title}
 
-```bash
-curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
+
+curl -X POST -H "X-API-Key: API_KEY" \
   https://api.datacommons.org/v2/resolve \
   -d '{"nodes": ["Mountain View, CA", "New York City"], "property": "<-description{typeOf:City}->dcid"}'
-```
+
>
 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
-
 ```json
 {
   "entities": [
@@ -390,6 +348,4 @@ Response:
       ]
     }
   ]
-}
-```
-{: .example-box-content .scroll}
\ No newline at end of file
+}
\ 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..b516ab6dc
--- /dev/null
+++ b/api/rest/v2/troubleshooting.md
@@ -0,0 +1,95 @@
+---
+layout: default
+title: Troubleshooting
+nav_order: 5
+parent: REST (v2)
+grand_parent: API
+published: true
+---
+
+{:.no_toc}
+# Troubleshoot common error responses
+
+* TOC
+{:toc}
+
+## "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

From dfe82df6d804d7d85dc36f6b8983b2788d573485 Mon Sep 17 00:00:00 2001
From: Kara Moscoe 
Date: Fri, 28 Jun 2024 09:09:15 -0700
Subject: [PATCH 2/8] more edits

---
 api/rest/v2/index.md       | 31 +++++++++++++++++-----------
 api/rest/v2/node.md        | 42 +++++++++++++++++++++++++-------------
 api/rest/v2/observation.md |  2 +-
 api/rest/v2/resolve.md     |  2 +-
 4 files changed, 49 insertions(+), 28 deletions(-)

diff --git a/api/rest/v2/index.md b/api/rest/v2/index.md
index b8dd9bded..a1b2e8561 100644
--- a/api/rest/v2/index.md
+++ b/api/rest/v2/index.md
@@ -108,13 +108,13 @@ API keys are required in any REST API request. To include an API key, add your A
 For GET requests, this looks like:
 
 
-https://api.datacommons.org/v2/endpoint?key=API_KEY
+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
+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:
@@ -159,7 +159,7 @@ For example, the request:
 
 curl --request GET \
   'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-*'
-
>
+

 
 will return something like:
 
@@ -176,10 +176,10 @@ will return something like:
 
 To get the next set of entries, repeat the previous command and append the `nextToken`:
 
-```bash
+
 curl --request GET \
   'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-*&nextToken=SoME_veRy_L0ng_S+rIng'
-```
+

 
 Similarly for POST requests, this would look like:
 
@@ -193,14 +193,21 @@ curl -X POST \
   "nextToken": "SoME_veRy_L0ng_S+rIng"
 

 
-
-
 {: #relation-expressions}
 ## Relation expressions
 
 Data Commons represents real world entities and data as nodes. These
 nodes are connected by directed edges, or arcs, to form a knowledge graph. The
-	@@ -60,41 +214,40 @@ The following table describes symbols in the V2 API relation expressions:
+label of the arc is the name of the [property](/glossary.html#property).
+
+Relation expressions include arrow annotation and other symbols in the syntax to
+represent neighboring nodes, and to support chaining and filtering.
+These new expressions allow all of the functionality of the V1 API to be
+expressed with fewer API endpoints in V2. All V2 API calls require relation
+expressions in the `property` or `expression` parameter.
+
+The following table describes symbols in the V2 API relation expressions:
+
 | ------ | ---------- |
 | `->` | An `out` arc |
 | `<-` | An `in` arc |
@@ -220,8 +227,8 @@ Note the directionality of the property `containedInPlace`: for the node "Argent
 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
 
@@ -230,12 +237,12 @@ You can use filters to reduce results to only match nodes with a specified prope
 ### Specify 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)).
+`->[name, latitude, longitude]` (this example is fully described in this [Node API example](/api/rest/v2/node.html#multiple-properties)).
 
 ### 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).
+This example is fully described in this [Node API example](/api/rest/v2/node.html#wildcard).
 
 ### Chain properties
 
diff --git a/api/rest/v2/node.md b/api/rest/v2/node.md
index 60d47182e..df0b793ab 100644
--- a/api/rest/v2/node.md
+++ b/api/rest/v2/node.md
@@ -71,16 +71,14 @@ JSON Data:
 
 
 
-### Query parameters
+## Query parameters
 
-| Name                                                  | Type   | Description                                                                                                                                                     |
-| ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Name                                                  | Type   |  Description           |
+| ----------------------------------------------------- | ------ | -----------------------|
 | key 
 Required      | string | Your API key. See the [page on authentication](/api/rest/v2/index.html#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 the [Data Commons REST (v2) API overview](/api/rest/v2/index.html#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.                            |
+| 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 the [Data Commons REST (v2) API overview](/api/rest/v2/index.html#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.   |
+
 {: .doc-table }
 
 ## Response
@@ -106,13 +104,14 @@ The response looks like:
   }
   "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 @@ -121,12 +120,15 @@ The response looks like: 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} @@ -137,6 +139,7 @@ curl --request GET --url \ Response: {: .example-box-title} + ```json { "data": { @@ -156,23 +159,27 @@ Response: ### 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} + ```bash nodes: "dc/03lw9rhpendw5" property: "->name" ``` + Request: {: .example-box-title} 
 curl --request GET --url \
-  'https://api.datacommons.org/v2/node?key=
API_KEY
&nodes=dc/03lw9rhpendw5&property=->name'
-```
+  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=dc/03lw9rhpendw5&property=->name'
+
+ Response: {: .example-box-title} + ```json { "data": { @@ -200,12 +207,15 @@ Response: 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} @@ -217,6 +227,7 @@ curl -X POST -H "X-API-Key: API_KEY" \ Response: {: .example-box-title} + ```json { "data": { @@ -283,10 +294,12 @@ Get all the `in` triples for node `PowerPlant` with property `<-*`. Parameters: {: .example-box-title} + ```bash nodes: "PowerPlant" property: "<-*" ``` + Request: {: .example-box-title} @@ -297,6 +310,7 @@ curl --request GET --url \ Response: {: .example-box-title} + ```json { "data": { diff --git a/api/rest/v2/observation.md b/api/rest/v2/observation.md index ceae1ad5c..2dbd5dfd2 100644 --- a/api/rest/v2/observation.md +++ b/api/rest/v2/observation.md @@ -73,7 +73,7 @@ Keep in mind the following rules when querying observations: 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 + 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. diff --git a/api/rest/v2/resolve.md b/api/rest/v2/resolve.md index 2c05e1370..58dd27dcc 100644 --- a/api/rest/v2/resolve.md +++ b/api/rest/v2/resolve.md @@ -27,7 +27,7 @@ the US state). The REST (v2) API introduces [relation expressions](/api/rest/v2/#relation-expressions) in the API syntax to represent -node relations, supporting chaining and filtering. For more information +node relations and support chaining and filtering. For more information see the [REST (v2) API overview](/api/rest/v2/index.html#relation-expressions). + ## Request +
@@ -56,7 +54,7 @@ https://api.datacommons.org/v2/node Header: X-API-Key: API_KEY -JSON Data: +JSON data: { "nodes": [ "VALUE1", diff --git a/api/rest/v2/observation.md b/api/rest/v2/observation.md index 2dbd5dfd2..7da09215c 100644 --- a/api/rest/v2/observation.md +++ b/api/rest/v2/observation.md @@ -8,28 +8,23 @@ published: true permalink: /api/rest/v2/observation --- -{:.no_toc} # /v2/observation -* TOC -{:toc} - 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 variable, entities, and dates. -Variables are specified as a list in the form of +Specify variables as a list, in this form: 
 {
-  "dcids": ["VARIABLE_DCID1", "VARIABLE_DCID2>"]
+  "dcids": ["VARIABLE_DCID1", "VARIABLE_DCID2"]
 }
-Specify entities as an enumerated list or node expression, as -follows: +Specify entities as an enumerated list or node expression, as follows: - Enumerated list: @@ -49,9 +44,9 @@ follows: You must specify dates using any of the following values: -- `LATEST`: to fetch the latest observations. -- `DATE_STRING: in the format YYYY, YYYY-MM, or YYYY-MM-DD, like `2020`, `2010-12`. -- `""`: a 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 @@ -82,7 +77,7 @@ See the examples below for use cases that use the preceding rules. ### 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} @@ -159,11 +154,11 @@ Response: ### Example 2: Get the observations at a particular date for given entities -This queries for observations in "2015" for 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} @@ -182,7 +177,7 @@ variable.dcids: "Count_Person" Request: {: .example-box-title} -`
+
 curl --request GET --url \
 'https://api.datacommons.org/v2/observation?key=API_KEY&date=2015&entity.dcids=country%2FUSA&entity.dcids=geoId%2F06&select=date&select=entity&select=value&select=variable&variable.dcids=Count_Person'
 

@@ -246,7 +241,7 @@ In this example, we use the [chained property
 [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:
diff --git a/api/rest/v2/resolve.md b/api/rest/v2/resolve.md
index 58dd27dcc..c85ae9efa 100644
--- a/api/rest/v2/resolve.md
+++ b/api/rest/v2/resolve.md
@@ -7,12 +7,8 @@ grand_parent: API
 published: true
 ---
 
-{:.no_toc}
 # /v2/resolve
 
-* TOC
-{:toc}
-
 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
@@ -32,7 +28,11 @@ see the [REST (v2) API overview](/api/rest/v2/index.html#relation-expressions).
 
 
+
+
 
+
 ## Request
+
 

   
   
 

 
@@ -63,7 +65,7 @@ https://api.datacommons.org/v2/resolve
 Header:
 X-API-Key: API_KEY
 
-JSON Data:
+JSON data:
 {
   "nodes": [
     "NODE1",
@@ -109,7 +111,7 @@ The response looks like:
       "candidates": [
         {
           "dcid": "DCID2",
-          "dominantType": "var>TYPE_OF_DCID2"
+          "dominantType": "TYPE_OF_DCID2"
         },
       ]
     },
@@ -120,20 +122,27 @@ The response looks like:
 {: .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}
+
 
+
 ## Examples
+
 ### Example 1: Find the DCID of a place by another known ID
+
 This queries for the DCID of a place by its Wikidata ID. This property is represented in the graph by [`wikidataId`](https://datacommons.org/browser/wikidataId).
+
 Parameters:
 {: .example-box-title}
+
 ```bash
 nodes: "Q30"
 property: "<-wikidataId->dcid"
@@ -144,11 +153,12 @@ Request:
 
 curl --request GET --url \
 'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Q30&property=<-wikidataId->dcid'
-```
+

 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
+
 ```json
 {
   "entities": [
@@ -165,12 +175,13 @@ 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, escape `#` to `%23`.
 
 Parameters:
 {: .example-box-title}
+
 ```bash
 nodes: "37.42#-122.08"
 property: "<-geoCoordinate->dcid"
@@ -178,14 +189,16 @@ property: "<-geoCoordinate->dcid"
 Request:
 {: .example-box-title}
 
-```bash
+
 curl --request GET --url \
 'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=37.42%23-122.08&property=<-geoCoordinate->dcid'
-```
+

+
 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
+
 ```json
 {
   "entities": [
@@ -203,7 +216,25 @@ Response:
         {
           "dcid": "geoId/06",
           "dominantType": "State"
-	@@ -240,27 +239,27 @@
+        },
+        {
+          "dcid": "country/USA",
+          "dominantType": "Country"
+        },
+        {
+          "dcid": "geoId/06085504601",
+          "dominantType": "CensusTract"
+        },
+        {
+          "dcid": "geoId/060855046011",
+          "dominantType": "CensusBlockGroup"
+        },
+        {
+          "dcid": "geoId/0608592830",
+          "dominantType": "CensusCountyDivision"
+        },
+        {
+          "dcid": "geoId/0618",
           "dominantType": "CongressionalDistrict"
         },
         {
@@ -233,21 +264,24 @@ Note that we use the `description` property in the request. This currently only
 
 Parameters:
 {: .example-box-title}
+
 ```bash
 nodes: "Georgia"
 property: "<-description->dcid"
 ```
+
 Request:
 {: .example-box-title}
 
 
 curl --request GET --url \
 'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Georgia&property=<-description->dcid
-```
+

 {: .example-box-content .scroll}
 
 Response:
 {: .example-box-title}
+
 ```json
 {
   "entities": [
@@ -261,16 +295,17 @@ 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 we also specify its type using a filter and only get one place in the response. Parameters: {: .example-box-title} + ```bash nodes: "Georgia" property: "<-description{typeOf:State}->dcid" @@ -286,6 +321,7 @@ curl --request GET --url \ Response: {: .example-box-title} + ```json { "entities": [ @@ -302,10 +338,11 @@ 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} + ```bash nodes: "Mountain View, CA", "New York City" property: "<-description{typeOf:City}->dcid" @@ -331,6 +368,7 @@ curl -X POST -H "X-API-Key: API_KEY" \ Response: {: .example-box-title} + ```json { "entities": [ @@ -348,4 +386,5 @@ Response: ] } ] -} \ 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 index 0fb0f5691..d27e0093c 100644 --- a/api/rest/v2/sparql.md +++ b/api/rest/v2/sparql.md @@ -18,21 +18,20 @@ queries to return specific information. ## Request -POST Request -{: .api-header} +
+ +
-
-URL: -https://api.datacommons.org/v2/sparql +
+URL: https://api.datacommons.org/v2/sparql -Header: -X-API-Key: API_KEY +Header: X-API-Key: API_KEY -JSON Data: -{ "sparql": "SPARQL_QUERY" } +JSON data: { "sparql": "SPARQL_QUERY" }
+ ### Query parameters diff --git a/api/rest/v2/troubleshooting.md b/api/rest/v2/troubleshooting.md index c4d9bff0d..2b6cacaa4 100644 --- a/api/rest/v2/troubleshooting.md +++ b/api/rest/v2/troubleshooting.md @@ -7,12 +7,8 @@ grand_parent: API published: true --- -{:.no_toc} # Troubleshoot common error responses -* TOC -{:toc} - ## "Method does not exist" ```json From 63b0a31ffb8c77d61219052f92ce5d21085a77b0 Mon Sep 17 00:00:00 2001 From: Kara Moscoe Date: Fri, 28 Jun 2024 11:14:10 -0700 Subject: [PATCH 5/8] restore demo key throughout --- api/index.md | 9 ++++----- api/rest/v2/getting_started.md | 2 -- api/rest/v2/index.md | 28 ++++++++++++++-------------- api/rest/v2/node.md | 30 +++++++++++++++--------------- api/rest/v2/observation.md | 20 ++++++++++---------- api/rest/v2/sparql.md | 12 ++++++------ 6 files changed, 49 insertions(+), 52 deletions(-) diff --git a/api/index.md b/api/index.md index e0f93aa76..1b7f548bf 100644 --- a/api/index.md +++ b/api/index.md @@ -13,19 +13,18 @@ database. Data Commons is based on the data model used by [schema.org](https://schema.org); for more information, see [the guide to the data model](/data_model.html). The Data Commons APIs allow developers to programmatically access the data in Data Commons. -Data Commons provides several different ways to access its API's resources: +Data Commons provides several different ways to access its resources: * A [REST API](/api/rest/v2) that can be used on the command line as well as in any language with an HTTP library. -* A lightweight [Python](/api/python) wrapper. -* A heavier [Pandas](/api/pandas) wrapper. +* [Python](/api/python) and [Pandas](/api/pandas) wrappers. The endpoints can be roughly grouped into four categories: +- **Statistical data**: Given a set of statistical variables, dates and entities, get observations. + - **Graph exploration**: Given a set of nodes, explore the graph around those nodes. -- **Statistical data**: Given a set of statistical variables, dates and entities, get observations. - - **Graph query/SPARQL**: Given a subgraph where some of the nodes are variables, retrieve possible matches. This corresponds to a subset of the graph query language [SPARQL](https://www.w3.org/TR/rdf-sparql-query/). This is useful for getting very specific observations which would require multiple API calls (e.g. "hate crimes motivated by disability status in Californian cities"). diff --git a/api/rest/v2/getting_started.md b/api/rest/v2/getting_started.md index 089f0c3b5..ac183808a 100644 --- a/api/rest/v2/getting_started.md +++ b/api/rest/v2/getting_started.md @@ -1,10 +1,8 @@ --- layout: redirect title: Getting Started Guide -nav_order: 0 parent: REST (v2) grand_parent: API -published: false permalink: /api/rest/v2/getting_started redirect: index.html --- \ No newline at end of file diff --git a/api/rest/v2/index.md b/api/rest/v2/index.md index a1b2e8561..5ffae9328 100644 --- a/api/rest/v2/index.md +++ b/api/rest/v2/index.md @@ -40,13 +40,13 @@ You make requests through [API endpoints](https://en.wikipedia.org/wiki/Web_API# The base URL for all REST endpoints is: 
-https://api.datacommons.org/VERSION_NUMBER
+https://api.datacommons.org/VERSION
-The current _VERSION_NUMBER_ is `v2`. +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: +The URIs for the V2 API are below: | API | URI path | Description | | --- | --- | ----------- | @@ -156,10 +156,10 @@ request with `nextToken` as an query parameter, with the token as its value. For example, the request: -
+```
 curl --request GET \
-  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-*'
-
+ 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-*' +``` will return something like: @@ -176,22 +176,22 @@ will return something like: To get the next set of entries, repeat the previous command and append the `nextToken`: -
+```
 curl --request GET \
-  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-*&nextToken=SoME_veRy_L0ng_S+rIng'
-
+ 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-*&nextToken=SoME_veRy_L0ng_S+rIng' +``` Similarly for POST requests, this would look like: -
+```json
 curl -X POST \
--H "X-API-Key: API_KEY" \
+-H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
 --url https://api.datacommons.org/v2/node \
 --data '{
   "nodes": "geoId/06",
   "property": "<-*",
   "nextToken": "SoME_veRy_L0ng_S+rIng"
-
+``` {: #relation-expressions} ## Relation expressions @@ -211,7 +211,7 @@ The following table describes symbols in the V2 API relation expressions: | ------ | ---------- | | `->` | An `out` arc | | `<-` | An `in` arc | -| PROPERTY:VALUE | Filtering; identifies the property and associated value | +| {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}` | @@ -232,7 +232,7 @@ Nodes from `out` arcs are represented by `->`, while nodes from ### Filters -You can use filters to reduce results to only match nodes with a specified property and value. Using the same example, `country/ARG<-containedInPlace+{typeOf:City}` only returns 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. ### Specify multiple properties diff --git a/api/rest/v2/node.md b/api/rest/v2/node.md index 07b9466f5..706b6df08 100644 --- a/api/rest/v2/node.md +++ b/api/rest/v2/node.md @@ -1,7 +1,7 @@ --- layout: default title: Node -nav_order: 2 +nav_order: 3 parent: REST (v2) grand_parent: API published: true @@ -44,7 +44,7 @@ see [Data Commons REST (v2) API overview](/api/rest/v2/index.html#relation-expre
-https://api.datacommons.org/v2/node?key=API_KEY&nodes=DCID&property=PROPERTY +https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=DCID&property=PROPERTY
@@ -52,7 +52,7 @@ URL: https://api.datacommons.org/v2/node Header: -X-API-Key: API_KEY +X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI JSON data: { @@ -130,10 +130,10 @@ property: "<-" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=geoId/06&property=<-'
-
+ 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-' +``` Response: {: .example-box-title} @@ -170,10 +170,10 @@ property: "->name" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=dc/03lw9rhpendw5&property=->name'
-
+ 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=dc/03lw9rhpendw5&property=->name' +``` Response: {: .example-box-title} @@ -217,11 +217,11 @@ property: "->[name, latitude, longitude]" Request: {: .example-box-title} -
-curl -X POST -H "X-API-Key: API_KEY" \
+```
+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} @@ -301,10 +301,10 @@ property: "<-*" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-  'https://api.datacommons.org/v2/node?key=API_KEY&nodes=PowerPlant&property=<-*'
-
+ 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=PowerPlant&property=<-*' +``` Response: {: .example-box-title} diff --git a/api/rest/v2/observation.md b/api/rest/v2/observation.md index 7da09215c..45b98b45c 100644 --- a/api/rest/v2/observation.md +++ b/api/rest/v2/observation.md @@ -1,7 +1,7 @@ --- layout: default title: Observation -nav_order: 3 +nav_order: 2 parent: REST (v2) grand_parent: API published: true @@ -95,10 +95,10 @@ variable.dcids: "Count_Person" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/observation?key=API_KEY&date=LATEST&entity.dcids=country%2FUSA&select=entity&select=variable&select=value&select=date&variable.dcids=Count_Person'
-
+'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' +``` {: .example-box-content .scroll} Response: @@ -177,10 +177,10 @@ variable.dcids: "Count_Person" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/observation?key=API_KEY&date=2015&entity.dcids=country%2FUSA&entity.dcids=geoId%2F06&select=date&select=entity&select=value&select=variable&variable.dcids=Count_Person'
-
+'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' +``` {: .example-box-content .scroll} Response: @@ -260,10 +260,10 @@ variable.dcids: "Count_Person" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/observation?key=API_KEY&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'
-
+'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' +``` {: .example-box-content .scroll} Response: diff --git a/api/rest/v2/sparql.md b/api/rest/v2/sparql.md index d27e0093c..5a7bf580b 100644 --- a/api/rest/v2/sparql.md +++ b/api/rest/v2/sparql.md @@ -25,9 +25,9 @@ queries to return specific information.
URL: https://api.datacommons.org/v2/sparql -Header: X-API-Key: API_KEY +Header: X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI -JSON data: { "sparql": "SPARQL_QUERY" } +JSON data: { "query": "SPARQL_QUERY" }
@@ -83,12 +83,12 @@ reverse alphabetical order. Request: {: .example-box-title} -
+```
 curl --request POST \
   --url https://api.datacommons.org/v2/sparql \
-  --header 'X-API-Key: API_KEY' \
+  --header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \
   --data '{
-            "sparql": "SELECT ?name \
+            "query": "SELECT ?name \
                 WHERE { \
                   ?biologicalSpecimen typeOf BiologicalSpecimen . \
                   ?biologicalSpecimen name ?name
@@ -96,7 +96,7 @@ curl --request POST \
                 ORDER BY DESC(?name)
                 LIMIT 10"
 }'
-
+``` {: .example-box-content .scroll} Response: From 2feb6e5f40e3c1da9768ba296f103c03fd56161c Mon Sep 17 00:00:00 2001 From: Kara Moscoe Date: Fri, 28 Jun 2024 11:23:10 -0700 Subject: [PATCH 6/8] minor fixes --- api/rest/v2/node.md | 2 +- api/rest/v2/resolve.md | 40 ++++++++++++++++++++-------------------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/api/rest/v2/node.md b/api/rest/v2/node.md index 706b6df08..ac2dc0680 100644 --- a/api/rest/v2/node.md +++ b/api/rest/v2/node.md @@ -132,7 +132,7 @@ Request: ``` curl --request GET --url \ - 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-' + 'https://api.datacommons.org/v2/node?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=geoId/06&property=<-' ``` Response: diff --git a/api/rest/v2/resolve.md b/api/rest/v2/resolve.md index c85ae9efa..fb92b006f 100644 --- a/api/rest/v2/resolve.md +++ b/api/rest/v2/resolve.md @@ -55,7 +55,7 @@ see the [REST (v2) API overview](/api/rest/v2/index.html#relation-expressions).
-https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=NODE_NAME&property=PROPERTY_EXPRESSION> +https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=NODE_NAME&property=PROPERTY_EXPRESSION>
@@ -63,7 +63,7 @@ URL: https://api.datacommons.org/v2/resolve Header: -X-API-Key: API_KEY +X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI JSON data: { @@ -150,10 +150,10 @@ property: "<-wikidataId->dcid" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Q30&property=<-wikidataId->dcid'
-
+'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Q30&property=<-wikidataId->dcid' +``` {: .example-box-content .scroll} Response: @@ -189,10 +189,10 @@ property: "<-geoCoordinate->dcid" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=37.42%23-122.08&property=<-geoCoordinate->dcid'
-
+'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=37.42%23-122.08&property=<-geoCoordinate->dcid' +``` {: .example-box-content .scroll} @@ -273,10 +273,10 @@ property: "<-description->dcid" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Georgia&property=<-description->dcid
-
+'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia&property=<-description->dcid +``` {: .example-box-content .scroll} Response: @@ -313,10 +313,10 @@ property: "<-description{typeOf:State}->dcid" Request: {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes=Georgia&property=<-description{typeOf:State}->dcid
-
+'https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=Georgia&property=<-description{typeOf:State}->dcid +``` {: .example-box-content .scroll} Response: @@ -350,20 +350,20 @@ property: "<-description{typeOf:City}->dcid" Request (GET): {: .example-box-title} -
+```
 curl --request GET --url \
-'https://api.datacommons.org/v2/resolve?key=API_KEY&nodes%3DMountain%20View%2C%20CA&nodes=New%20York%20City&property=%3C-description%7BtypeOf%3ACity%7D-%3Edcid'
-
+'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' +``` {: .example-box-content .scroll} Request (POST): {: .example-box-title} -
-curl -X POST -H "X-API-Key: API_KEY" \
+```
+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"}'
-
> +``` {: .example-box-content .scroll} Response: From 5c9ec557eec8dc4e6805a9be8398045191e3560d Mon Sep 17 00:00:00 2001 From: Carolyn Au Date: Fri, 28 Jun 2024 14:47:50 -0700 Subject: [PATCH 7/8] test commit --- api/rest/v2/observation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/rest/v2/observation.md b/api/rest/v2/observation.md index 45b98b45c..9840ede03 100644 --- a/api/rest/v2/observation.md +++ b/api/rest/v2/observation.md @@ -18,11 +18,11 @@ and so on. When querying observations, you need to provide variable, entities, and dates. Specify variables as a list, in this form: -
+```json-doc
 {
-  "dcids": ["VARIABLE_DCID1", "VARIABLE_DCID2"]
+  "dcids": [_VARIABLE_DCID1_, _VARIABLE_DCID2_]
 }
-
+``` Specify entities as an enumerated list or node expression, as follows: From 846e41d7f65ba57924f0318e27dcc7b4a05aafc3 Mon Sep 17 00:00:00 2001 From: Carolyn Au Date: Fri, 28 Jun 2024 15:30:42 -0700 Subject: [PATCH 8/8] example formatter options --- _sass/friendly_code.scss | 5 ++++- api/rest/v2/observation.md | 36 +++++++++++++++++++++++++++++++++++- 2 files changed, 39 insertions(+), 2 deletions(-) diff --git a/_sass/friendly_code.scss b/_sass/friendly_code.scss index 4339b108e..796a8844d 100644 --- a/_sass/friendly_code.scss +++ b/_sass/friendly_code.scss @@ -61,4 +61,7 @@ .highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ .highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ .highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ -.highlight .il { color: #40a070 } /* Literal.Number.Integer.Long */ \ No newline at end of file +.highlight .il { color: #40a070 } /* Literal.Number.Integer.Long */ + +.language-json-doc .err { border: none; font-style: italic } +.language-js .nx { font-style: italic; color: #007020; } \ No newline at end of file diff --git a/api/rest/v2/observation.md b/api/rest/v2/observation.md index 9840ede03..efbbc9e36 100644 --- a/api/rest/v2/observation.md +++ b/api/rest/v2/observation.md @@ -18,9 +18,43 @@ and so on. When querying observations, you need to provide variable, entities, and dates. Specify variables as a list, in this form: +yaml +```yaml +{ + "dcids": [VARIABLE_DCID_1, VARIABLE_DCID_2] + "dcids": ["", ""] +} +``` + +json-doc ```json-doc { - "dcids": [_VARIABLE_DCID1_, _VARIABLE_DCID2_] + "dcids": [VARIABLE_DCID_1, VARIABLE_DCID_2], + "dcids": ["", ""] +} +``` + +elixir +```elixir +{ + "dcids": [VARIABLE_DCID_1, VARIABLE_DCID_2], + "dcids": ["", ""] +} +``` + +js +```js +{ + "dcids": [VARIABLE_DCID_1, VARIABLE_DCID_2], + "dcids": ["", ""] +} +``` + +go +```go +{ + "dcids": [VARIABLE_DCID_1, VARIABLE_DCID_2], + "dcids": ["", ""] } ```