{"openapi":"3.1.0","info":{"title":"Data Commons (BYOK) API","version":"0.1.0","description":"Data Commons (BYOK) lets an AI assistant read your own Data Commons data through the Data Commons API with a key you supply (Data Commons API key). Read-only: 11 tools (find_place_by_name, find_place_by_coordinates, find_statistical_variables, get_place_basics, list_places_within, query_knowledge_graph, get_latest_observation, get_observation_series, get_observation_for_date,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-datacommons.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-datacommons/docs"},"termsOfService":"https://connectorbay.com/byok-datacommons/terms"},"servers":[{"url":"https://byok-datacommons.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-datacommons/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/find_place_by_name":{"post":{"operationId":"find_place_by_name","summary":"Resolve a place name to Data Commons place ids (DCIDs); add context such as state or country to avoid ambiguity. Use for","description":"Resolve a place name to Data Commons place ids (DCIDs); add context such as state or country to avoid ambiguity. Use for \"What is the Data Commons id of Pune, India\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Place name with context, for example 'Pune, Maharashtra, India' or 'Georgia'.","maxLength":200,"title":"Name","type":"string"}},"required":["name"],"title":"find_place_by_nameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_place_by_coordinates":{"post":{"operationId":"find_place_by_coordinates","summary":"Find the places (city, county, state, country) that contain a latitude and longitude. Use for \"Which places contain coor","description":"Find the places (city, county, state, country) that contain a latitude and longitude. Use for \"Which places contain coordinates 19.07, 72.88\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"coordinates":{"description":"Latitude and longitude joined by '#', for example '37.42#-122.08'.","maxLength":40,"title":"Coordinates","type":"string"}},"required":["coordinates"],"title":"find_place_by_coordinatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_statistical_variables":{"post":{"operationId":"find_statistical_variables","summary":"Search statistical variables (population, GDP, life expectancy, emissions and thousands more) by keywords and get their ","description":"Search statistical variables (population, GDP, life expectancy, emissions and thousands more) by keywords and get their ids with a match score. Use for \"Which Data Commons variables measure life expectancy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Topic words, for example 'population' or 'infant mortality'.","maxLength":200,"title":"Query","type":"string"}},"required":["query"],"title":"find_statistical_variablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_place_basics":{"post":{"operationId":"get_place_basics","summary":"Get the name, latitude and longitude of one or more places by DCID. Use for \"What are the coordinates of California in D","description":"Get the name, latitude and longitude of one or more places by DCID. Use for \"What are the coordinates of California in Data Commons\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dcid":{"description":"Place id (DCID), for example 'geoId/06'.","maxLength":100,"title":"Dcid","type":"string"}},"required":["dcid"],"title":"get_place_basicsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_places_within":{"post":{"operationId":"list_places_within","summary":"List the places of one type inside a parent place, for example all states of a country or all counties of a state. Use f","description":"List the places of one type inside a parent place, for example all states of a country or all counties of a state. Use for \"List all the states in India\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parent_dcid":{"description":"Parent place id (DCID), for example 'country/IND' or 'geoId/06'.","maxLength":100,"title":"Parent Dcid","type":"string"},"child_type":{"description":"Relation expression for the type of child places to list.","enum":["<-containedInPlace+{typeOf:Country}","<-containedInPlace+{typeOf:State}","<-containedInPlace+{typeOf:County}","<-containedInPlace+{typeOf:City}"],"title":"Child Type","type":"string"}},"required":["parent_dcid","child_type"],"title":"list_places_withinArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/query_knowledge_graph":{"post":{"operationId":"query_knowledge_graph","summary":"Read graph properties of a node with a relation expression, for example '->name', '->[name, latitude]' or '<-typeOf'; re","description":"Read graph properties of a node with a relation expression, for example '->name', '->[name, latitude]' or '<-typeOf'; returns arcs and may include a nextToken. Use for \"What are the incoming property labels of geoId/06\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dcid":{"description":"Node id (DCID) to read, for example 'geoId/06' or 'Count_Person'.","maxLength":100,"title":"Dcid","type":"string"},"property":{"description":"Relation expression, for example '->name' (outgoing name), '<-' (incoming labels) or '->[name, description]'.","maxLength":200,"title":"Property","type":"string"}},"required":["dcid","property"],"title":"query_knowledge_graphArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_latest_observation":{"post":{"operationId":"get_latest_observation","summary":"Get the most recent value of a statistical variable for a place, with the source dataset (facet) details. Use for \"What ","description":"Get the most recent value of a statistical variable for a place, with the source dataset (facet) details. Use for \"What is the latest population of India\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variable":{"description":"Statistical variable id (DCID), for example 'Count_Person' (population) or 'Count_Person_Female'. Find ids with find_statistical_variables.","maxLength":200,"title":"Variable","type":"string"},"entity":{"description":"Place id (DCID), for example 'country/IND', 'geoId/06' (California) or 'wikidataId/Q668'. Find ids with find_place_by_name.","maxLength":100,"title":"Entity","type":"string"}},"required":["variable","entity"],"title":"get_latest_observationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_observation_series":{"post":{"operationId":"get_observation_series","summary":"Get all dated values of a statistical variable for a place, grouped by source dataset (facet); long series are shortened","description":"Get all dated values of a statistical variable for a place, grouped by source dataset (facet); long series are shortened by the connector. Use for \"Show India's population over time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variable":{"description":"Statistical variable id (DCID), for example 'Count_Person' (population) or 'Count_Person_Female'. Find ids with find_statistical_variables.","maxLength":200,"title":"Variable","type":"string"},"entity":{"description":"Place id (DCID), for example 'country/IND', 'geoId/06' (California) or 'wikidataId/Q668'. Find ids with find_place_by_name.","maxLength":100,"title":"Entity","type":"string"}},"required":["variable","entity"],"title":"get_observation_seriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_observation_for_date":{"post":{"operationId":"get_observation_for_date","summary":"Get the value of a statistical variable for a place at one date; the date format depends on the variable (2020, 2020-06 ","description":"Get the value of a statistical variable for a place at one date; the date format depends on the variable (2020, 2020-06 or 2020-06-15). Use for \"What was India's population in 2011\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variable":{"description":"Statistical variable id (DCID), for example 'Count_Person' (population) or 'Count_Person_Female'. Find ids with find_statistical_variables.","maxLength":200,"title":"Variable","type":"string"},"entity":{"description":"Place id (DCID), for example 'country/IND', 'geoId/06' (California) or 'wikidataId/Q668'. Find ids with find_place_by_name.","maxLength":100,"title":"Entity","type":"string"},"date":{"description":"Date in the variable's own format, for example '2011' (yearly) or '2020-06' (monthly).","maxLength":10,"title":"Date","type":"string"}},"required":["variable","entity","date"],"title":"get_observation_for_dateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compare_places_latest":{"post":{"operationId":"compare_places_latest","summary":"Get the latest value of a variable for every place matched by a containment expression, such as all counties of a state.","description":"Get the latest value of a variable for every place matched by a containment expression, such as all counties of a state. Use for \"Compare the latest population of every county in California\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variable":{"description":"Statistical variable id (DCID), for example 'Count_Person' (population) or 'Count_Person_Female'. Find ids with find_statistical_variables.","maxLength":200,"title":"Variable","type":"string"},"entity_expression":{"description":"Entity expression, for example 'geoId/06<-containedInPlace+{typeOf:County}' (all counties of California).","maxLength":200,"title":"Entity Expression","type":"string"}},"required":["variable","entity_expression"],"title":"compare_places_latestArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_data_sources":{"post":{"operationId":"list_data_sources","summary":"Show which source datasets (facets) hold a variable for a place, with date range and observation count, without returnin","description":"Show which source datasets (facets) hold a variable for a place, with date range and observation count, without returning values. Use for \"Which datasets provide India's population and for which years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variable":{"description":"Statistical variable id (DCID), for example 'Count_Person' (population) or 'Count_Person_Female'. Find ids with find_statistical_variables.","maxLength":200,"title":"Variable","type":"string"},"entity":{"description":"Place id (DCID), for example 'country/IND', 'geoId/06' (California) or 'wikidataId/Q668'. Find ids with find_place_by_name.","maxLength":100,"title":"Entity","type":"string"}},"required":["variable","entity"],"title":"list_data_sourcesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}