Walkthrough B: an indicator across child places

The second research pattern, run for real: how does access to safely managed drinking water compare across the world’s countries? That is SDG indicator 6.1.1. The parent geography is the world and the child places are its countries — the normal shape of a child-places question on this instance, which publishes observations for countries and for supranational geographies (see Geographic scope). Step 4 repeats the retrieval for one UN region. As on Walkthrough A, every cell executes against the live server at build time. The pattern is the child-places playbook’s: discover with a sample of children → assess → retrieve for every child of a type.

import sys
from pathlib import Path

sys.path.insert(0, str(Path.cwd().parents[1]))
from plugins.mcp_client import McpClient, call_tool
from plugins import walkthrough as wt

client = McpClient()
client.initialize()["serverInfo"]

1. Discover: search_child_indicators¶

The child-places search needs the parent place and a sample of child places, so it can check that candidate indicators actually have data at that level. The playbook suggests five or six diverse children; the world resolves to the DCID Earth.

found = call_tool(
    client,
    "search_child_indicators",
    query="safely managed drinking water",
    parent_place="World",
    sample_child_places=["Rwanda", "Kenya", "Brazil", "India", "Norway"],
    include_topics=False,
    per_search_limit=8,
)
wt.candidates(found)

The candidates mix the SDG series with UNICEF’s WASH breakdowns. The headline SDG indicator is undata/sdg/SH_H2O_SAFE; the “places with data” column already tells us which of our sample countries it covers. We proceed with that DCID explicitly.

2. Assess: get_variable_metadata¶

With entity_dcids=["Earth"] the metadata describes coverage for the parent.

variable = "undata/sdg/SH_H2O_SAFE"
meta = call_tool(client, "get_variable_metadata", variable_dcids=[variable], entity_dcids=["Earth"])
wt.facets(meta, variable)

One facet from the SDG global database, annual, 2000 onwards.

3. Retrieve: get_child_observations¶

Now every country at once. The playbook’s rule for this tool is firm: with child_place_type set, never ask for date="all" — the answer multiplies by the number of children. "latest" returns one value per country, and note that “latest” is not the same year everywhere: the date column says which year each value is from. One more thing to expect on the current platform: for an answer this large, the entityMetadata names run out for the tail of the country list, although every observation is present. The table below shows the DCID wherever the name is blank.

obs = call_tool(
    client,
    "get_child_observations",
    variable_dcid=variable,
    parent_place_dcid="Earth",
    child_place_type="Country",
    date="latest",
)
countries = wt.child_observations(obs)
countries.head(10)

Source

wt.extremes_chart(
    countries,
    title=obs["variable"]["name"],
    unit=obs["sourceMetadata"].get("unit", ""),
)

years = countries["date"].value_counts().sort_index()
print(
    f"{len(countries)} countries; latest values span {years.index[0]}–{years.index[-1]}; "
    f"source {obs['sourceMetadata']['provenanceUrl']}"
)

163 countries; latest values span 2017–2024; source https://unstats.un.org/sdgs/dataportal

4. The same pattern for a UN region¶

A continent, a UN region or another geographic grouping is the parent in exactly the same way. Its DCID is not guessed: the discovery call resolves the name and returns the DCID as resolvedParentPlace, while confirming that the sampled countries have data for the candidates.

found = call_tool(
    client,
    "search_child_indicators",
    query="safely managed drinking water",
    parent_place="Sub-Saharan Africa",
    sample_child_places=["Kenya", "Nigeria", "Ghana", "Zambia", "Senegal"],
    include_topics=False,
    per_search_limit=8,
)
region = found["resolvedParentPlace"]
region

obs = call_tool(
    client,
    "get_child_observations",
    variable_dcid=variable,
    parent_place_dcid=region["dcid"],
    child_place_type="Country",
    date="latest",
)
region_countries = wt.child_observations(obs)
print(
    f"{len(region_countries)} countries returned for {region['name']}; "
    f"source {obs['sourceMetadata']['provenanceUrl']}"
)
region_countries.head(10)

26 countries returned for Sub-Saharan Africa; source https://unstats.un.org/sdgs/dataportal

The countries returned are those the knowledge graph records as contained in the region: that containment is what child_place_type traverses, and it need not coincide with an official membership list.

Every figure above is attributable: the source in the last line is what the server’s instructions require you to cite alongside the numbers.