Add documentation of new Resolve API parameters #670

kmoscoe · 2026-01-29T04:04:22Z

This PR also:

Adds a definition of topics to the glossary
Cleans up an obsolete glossary entry

Staged at https://bullie.svl.corp.google.com:4000

…to api

gemini-code-assist · 2026-01-29T04:04:47Z

Summary of Changes

Hello @kmoscoe, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Data Commons Resolve API by extending its functionality beyond geographical places to include statistical variables and topics. It introduces new parameters and a dedicated method in the Python client library, along with corresponding updates to the REST API documentation. The changes aim to provide developers with more powerful and flexible tools for identifying and retrieving specific data entities within the Data Commons knowledge graph, while also improving the overall clarity and accuracy of the documentation.

Highlights

Expanded Resolve API Capabilities: The Resolve API now supports resolving statistical variables and topics in addition to place entities, offering more comprehensive data retrieval.
New Python API Method: A new fetch_indicators method has been introduced in the Python API for directly resolving statistical variables and topics.
Updated Python fetch Method: The existing fetch method in the Python API has been enhanced with resolver and target parameters, allowing for more flexible entity resolution, including statistical variables and topics.
REST API Enhancements: The REST API's resolve endpoint has been updated to include resolver and target parameters, aligning its functionality with the new Python API capabilities.
Comprehensive Documentation for Resolve API: Detailed explanations of new parameters, updated response structures, and new examples have been added for both Python and REST Resolve APIs to reflect the expanded functionality.
Glossary Updates: A new definition for 'Topic' has been added to the glossary, and an obsolete 'Cohort' entry has been removed for clarity.
API Key Requirements Clarification: The documentation for API key requirements now explicitly includes Data Commons MCP server requests.
Python Node API Method Renamed: The fetch_place_place_descendants method in the Python Node API has been corrected to fetch_place_descendants.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request does a great job of documenting the new parameters for the Resolve API, especially the ability to resolve statistical variables and topics. The addition of the 'Topic' definition to the glossary and the cleanup of the obsolete 'Cohort' entry are also valuable improvements. I've identified a few minor inconsistencies in the documentation for both the Python and REST APIs, mainly regarding parameter and field types not matching the examples. Addressing these will enhance the clarity and accuracy of the documentation for developers.

api/python/v2/resolve.md

api/rest/v2/resolve.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

clincoln8

Thanks Kara! Left a few nits, but looks great overall!

clincoln8 · 2026-01-30T02:20:13Z

api/python/v2/resolve.md

+You can also query for statistical variables and topics. For example, you could find the DCIDs for all statistical variables containing the string "population".

-> **Note**: Currently, this endpoint only supports [place](/glossary.html#place) entities.
+Note that you can only resolve entities by some terminal properties. You cannot resolve properties that represent linked entities with incoming or outgoing arc relationships. For that, you need to use the [Node](node.md) API. For example, if you wanted to get all the DCIDs of entities that are related to a given entity by the `containedInPlace` property (say, all states in the United States), use the Node API.


I think the way our endpoint is currently written, that we don't really need this note.
I believe the vision was that you'd be able to supply any property in the property= <-{property}->dcid request param and resolve on it. This would warrant this note of only using terminal properties. However that logic is not implemented and we make it very explicit that only "description" is valid for indicators and "description|wikidataId|geoCoordinates" is valid for places.
So this note seems unnecessary for now and could be added back if we ever support resolving based on generic properties.

Suggested change

Note that you can only resolve entities by some terminal properties. You cannot resolve properties that represent linked entities with incoming or outgoing arc relationships. For that, you need to use the [Node](node.md) API. For example, if you wanted to get all the DCIDs of entities that are related to a given entity by the `containedInPlace` property (say, all states in the United States), use the Node API.

We could keep the part about "use Node API if you want to fetch more data about each returned candidate"

clincoln8 · 2026-01-30T02:23:40Z

api/python/v2/resolve.md

 the US state).

-Note that you can only resolve entities by some terminal properties. You cannot resolve properties that represent linked entities with incoming or outgoing arc relationships. For that, you need to use the [Node](node.md) API. For example, if you wanted to get all the DCIDs of entities that are related to a given entity by the `containedInPlace` property (say, all states in the United States), use the Node API.
+You can also query for statistical variables and topics. For example, you could find the DCIDs for all statistical variables containing the string "population".


nit:

Suggested change

You can also query for statistical variables and topics. For example, you could find the DCIDs for all statistical variables containing the string "population".

You can also query for statistical variables and topics. For example, you could find the DCIDs for all statistical variables related to the string "population".

Resolve is based on semantic embeddings, not text based search.

clincoln8 · 2026-01-30T02:33:01Z

api/python/v2/resolve.md

+| [fetch_dcid_by_coordinates](#fetch_dcid_by_coordinates) | Look up a DCID of a single place by geographical coordinates. |
+| [fetch_indicators](#fetch_indicators) | Look up the DCIDs of all matching statistical variables and topics. |

 ## Response


It might make sense to list the default value response first -- for resolving places, response looks like xyz. For the fetch_indicators and fetch w/resolver=indicator response looks like abc.

clincoln8 · 2026-01-30T02:34:55Z

api/python/v2/resolve.md

-| dominantType | string | Optional field which, where present, disambiguates between multiple results. |
+| node | string | The query terms used to look up the DCIDs of entities. |
+| candidates | list | List of nodes that match the query terms. |
+| dominantType | string | Optional field which, when present, disambiguates between multiple results. Only returned when `resolver` is set to `place` (the default). |


nit: dcid is not listed as a field, is that intentional? i'm not sure if it's necessary or not since it seems self explanatory.

clincoln8 · 2026-01-30T02:37:17Z

api/python/v2/resolve.md

-| expression <br /> <required-tag>Required</required-tag> | string | An expression that describes the identifier used in the `node_ids` parameter. Only three are currently supported: <br />`<-description`: Search for nodes based on name-related properties (such as `name`, `alternateName`, etc.).<br/>`<-wikidataId`: Search for nodes based on their Wikidata ID(s).<br/>`<-geoCoordinates`: Search for nodes based on latitude and/or longitude.<br/> Note that these are not necessarily "properties" that appear in the knowledge graph; instead, they are "synthetic" attributes that cover searches over multiple properties. <br/>Each expression must end with `->dcid` and may optionally include a [`typeOf` filter](/api/rest/v2/index.html#filters). |
+| node_ids <br /> <required-tag>Required</required-tag>  | string or list of strings | A list of terms that identify each node to search for, such as their names. A single string can contain spaces and commas. |
+| resolver <br /> <optional-tag>Optional</optional-tag> | string literal | Currently accepted options are `place` (the default) and `indicator`, which resolves statistical variables. If not specified, the default is `place`. |
+| expression <br /> <optional-tag>Optional</optional-tag>  | string | An expression that describes the identifier used in the `nodes` parameter. Only three are currently supported:<br />`<-description`: Search for nodes based on name-related properties (such as `name`, `alternateName`, etc.).<br/>`<-wikidataId`: Search for nodes based on their Wikidata ID(s).<br/>`<-geoCoordinates`: Search for nodes based on latitude and/or longitude. <br/>If not specified, the default is `<-description`. <br/>Each expression must end with `->dcid` and may optionally include a [`typeOf` filter](/api/rest/v2/index.html#filters). <br/><b>Note:</b> To specify `wikidataId`,`geoCoordinates`, or a `typeOf` filter on the query, you must specify this parameter. <br/> Note: The `description` field is not necessarily present in the knowledge graph for all entities. It is a synthetic property that Data Commons uses to check various name-related fields, such as `name`. The `geoCoordinates` field is a synthesis of `latitude` and `longitude` properties. |


Suggested change

| expression <optional-tag>Optional</optional-tag> | string | An expression that describes the identifier used in the `nodes` parameter. Only three are currently supported: `<-description`: Search for nodes based on name-related properties (such as `name`, `alternateName`, etc.). `<-wikidataId`: Search for nodes based on their Wikidata ID(s). `<-geoCoordinates`: Search for nodes based on latitude and/or longitude. If not specified, the default is `<-description`. Each expression must end with `->dcid` and may optionally include a [`typeOf` filter](/api/rest/v2/index.html#filters). Note: To specify `wikidataId`,`geoCoordinates`, or a `typeOf` filter on the query, you must specify this parameter. Note: The `description` field is not necessarily present in the knowledge graph for all entities. It is a synthetic property that Data Commons uses to check various name-related fields, such as `name`. The `geoCoordinates` field is a synthesis of `latitude` and `longitude` properties. |

| expression <optional-tag>Optional</optional-tag> | string | An expression that describes the identifier used in the `nodes` parameter. Only three are currently supported: `<-description`: Search for nodes based on name-related properties (such as `name`, `alternateName`, etc.). `<-wikidataId`: Search for nodes based on their Wikidata ID(s). (for place resolution only) `<-geoCoordinates`: Search for nodes based on latitude and/or longitude. for place resolution only) If not specified, the default is `<-description`. Each expression must end with `->dcid` and may optionally include a [`typeOf` filter](/api/rest/v2/index.html#filters). Note: To specify `wikidataId`,`geoCoordinates`, or a `typeOf` filter on the query, you must specify this parameter. Note: The `description` field is not necessarily present in the knowledge graph for all entities. It is a synthetic property that Data Commons uses to check various name-related fields, such as `name`. The `geoCoordinates` field is a synthesis of `latitude` and `longitude` properties. |

clincoln8 · 2026-01-30T02:52:47Z

api/rest/v2/resolve.md


 <div id="GET-request" class="api-tabcontent api-signature">
-https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=<var>IDENTIFIER_LIST</var>&property=<var>EXPRESSION</var>
+https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=<var>IDENTIFIER_LIST</var>&resolver=<var>NODE_TYPE</var>&property=<var>EXPRESSION</var>&target=<var>INSTANCE</var>


Suggested change

https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=<var>IDENTIFIER_LIST</var>&resolver=<var>NODE_TYPE</var>&property=<var>EXPRESSION</var>&target=<var>INSTANCE</var>

https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=<var>IDENTIFIER_LIST</var>&resolver=<var>RESOLUTION_TYPE</var>&property=<var>EXPRESSION</var>&target=<var>INSTANCE</var>

clincoln8 · 2026-01-30T02:53:01Z

api/rest/v2/resolve.md

    ...
  ],
-  "property": "<var>EXPRESSION</var>"
+  "resolver": "<var>NODE_TYPE</var>",


Suggested change

"resolver": "<var>NODE_TYPE</var>",

"resolver": "<var>RESOLUTION_TYPE</var>",

clincoln8 · 2026-01-30T02:54:24Z

api/rest/v2/resolve.md

@@ -116,7 +168,10 @@ The response looks like:
 |-------------|--------|-------------------------------------|
 | node | string | The property value or description provided. |
 | candidates | list | DCIDs matching the description you provided. |


candidates is a list of nodes. each node contains dcid, dominantType (optional), metadata (optional), typeOf (optional)

clincoln8 · 2026-01-30T02:56:22Z

api/rest/v2/resolve.md

+
+(truncated)
+
+```json


Suggested change

```json

```jsonc

clincoln8 · 2026-01-30T02:56:52Z

api/rest/v2/resolve.md

+          "dcid": "Count_Person_18OrMoreYears",
+          "metadata": {
+            "score": "0.8167",
+            "sentence": "adult population count"
+          },
+          "typeOf": [
+            "StatisticalVariable"
+          ]
+        },
+        {
+          "dcid": "Count_Person_Upto18Years",
+          "metadata": {
+            "score": "0.8121",
+            "sentence": "children population count"
+          },
+          "typeOf": [
+            "StatisticalVariable"
+          ]
+        },


Suggested change

"dcid": "Count_Person_18OrMoreYears",

"metadata": {

"score": "0.8167",

"sentence": "adult population count"

},

"typeOf": [

"StatisticalVariable"

]

},

{

"dcid": "Count_Person_Upto18Years",

"metadata": {

"score": "0.8121",

"sentence": "children population count"

},

"typeOf": [

"StatisticalVariable"

]

},

// ...

]}]}

kmoscoe and others added 30 commits June 11, 2025 19:07

remove references to dataclass objects

d6241c9

Fix a copy-paste error.

101c5fd

remove extra file

504d852

Merge branch 'datacommonsorg:master' into master

1697b22

Merge branch 'master' of https://github.com/datacommonsorg/docsite

426a81c

Merge branch 'master' of https://github.com/kmoscoe/docsite

a40c7c8

Merge branch 'datacommonsorg:master' into master

4c69c15

Merge branch 'datacommonsorg:master' into master

dd5b50f

Merge branch 'datacommonsorg:master' into master

23cb4c4

Merge branch 'datacommonsorg:master' into master

1157311

Merge branch 'datacommonsorg:master' into master

23d3429

Merge branch 'datacommonsorg:master' into master

2a3409f

Merge branch 'master' of https://github.com/datacommonsorg/docsite

516ed75

Merge branch 'datacommonsorg:master' into master

564457c

Merge branch 'datacommonsorg:master' into master

7052453

Merge branch 'datacommonsorg:master' into master

5da50d1

Merge branch 'master' of https://github.com/kmoscoe/docsite

a011388

Merge branch 'datacommonsorg:master' into master

12b9749

Merge branch 'datacommonsorg:master' into master

f4861e4

Fix a copy-paste error.

33234d2

Merge branch 'datacommonsorg:master' into master

169781f

Merge branch 'master' of https://github.com/datacommonsorg/docsite

f3a9005

Merge branch 'datacommonsorg:master' into master

205cb04

Merge branch 'master' of https://github.com/datacommonsorg/docsite

3daf24f

Merge branch 'datacommonsorg:master' into master

7599eff

Merge branch 'master' of https://github.com/kmoscoe/docsite

4dd0251

Remove unused file

54ca4cf

Merge branch 'master' of https://github.com/datacommonsorg/docsite

5ab6c5c

Merge branch 'datacommonsorg:master' into master

1c2a36c

Merge branch 'datacommonsorg:master' into master

5d2800b

kmoscoe and others added 16 commits December 3, 2025 15:09

Merge branch 'datacommonsorg:master' into master

b2cbfd4

Merge branch 'datacommonsorg:master' into master

494375d

Merge branch 'datacommonsorg:master' into master

f4da5c3

Merge branch 'datacommonsorg:master' into master

73c0d41

Merge branch 'datacommonsorg:master' into master

735db87

Merge branch 'datacommonsorg:master' into master

d165d9e

Merge branch 'master' of https://github.com/datacommonsorg/docsite

4559295

Merge branch 'master' of https://github.com/kmoscoe/docsite

85d15a4

Merge branch 'master' of https://github.com/datacommonsorg/docsite

d80ed79

Merge branch 'master' of https://github.com/datacommonsorg/docsite

6184f92

Start draft on new resolver parameters

4994889

Merge branch 'master' of https://github.com/datacommonsorg/docsite in…

171028b

…to api

first draft of new resolve API

9e5f038

First complete draft of new resolve API parameter

5464aaa

cut redundant text

c0ba399

Remove cohort from glossary

2a581dc

gemini-code-assist bot reviewed Jan 29, 2026

View reviewed changes

api/python/v2/resolve.md Show resolved Hide resolved

api/python/v2/resolve.md Outdated Show resolved Hide resolved

api/python/v2/resolve.md Outdated Show resolved Hide resolved

api/rest/v2/resolve.md Show resolved Hide resolved

kmoscoe and others added 2 commits January 29, 2026 15:06

Update api/python/v2/resolve.md

56506a2

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Update api/python/v2/resolve.md

c435dfc

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

kmoscoe requested review from clincoln8 and keyurva January 29, 2026 23:09

clincoln8 approved these changes Jan 30, 2026

View reviewed changes

	You can also query for statistical variables and topics. For example, you could find the DCIDs for all statistical variables containing the string "population".
	You can also query for statistical variables and topics. For example, you could find the DCIDs for all statistical variables related to the string "population".

	https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=<var>IDENTIFIER_LIST</var>&resolver=<var>NODE_TYPE</var>&property=<var>EXPRESSION</var>&target=<var>INSTANCE</var>
	https://api.datacommons.org/v2/resolve?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&nodes=<var>IDENTIFIER_LIST</var>&resolver=<var>RESOLUTION_TYPE</var>&property=<var>EXPRESSION</var>&target=<var>INSTANCE</var>

	"resolver": "<var>NODE_TYPE</var>",
	"resolver": "<var>RESOLUTION_TYPE</var>",


		(truncated)

		```json

Add documentation of new Resolve API parameters #670

Are you sure you want to change the base?

Add documentation of new Resolve API parameters #670

Uh oh!

Conversation

kmoscoe commented Jan 29, 2026

Uh oh!

gemini-code-assist bot commented Jan 29, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clincoln8 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants