Concepts

The identifier used by the Data Commons knowledge graph for an entity — a place, a statistical variable, a topic. Tools generally expect DCIDs rather than display labels once a specific entity or variable has been selected; discovery is how you obtain them.

A DCID is an identifier, not evidence of membership: a shared place such as country/RWA is used by this deployment as it is. For normal research workflows, use statistical-variable DCIDs returned by the UN System Data Commons discovery workflow — see Statistical scope.

Identifies what is being measured: one series published by a UN agency, with zero or more of its dimensions fixed to particular values. A variable with no fixed dimension is the total, or unconstrained, member of its family. Once a dimension is fixed in a variable it does not vary among that variable’s observations; only the place and the date do.

The get_variable_metadata response states this structure:

• populationType names the series, which is the family the variable belongs to;

• constraintProperties lists the dimensions fixed in this variable (one name as a string, several as a list, absent when none is fixed);

• each fixed dimension also appears as a property of its own, such as undataAge or undataSex, holding the label of the fixed value.

The displayed name summarizes the same constraints as series label [Dimension=Value, …]. UNICEF’s undata/unicef/DM_POP is Total population, and undata/unicef/DM_POP.AGE--Y0T17__SEX--F is Total population [Age=Under 18 years old, Sex=Female], whose metadata carries constraintProperties Age and Sex, undataAge Under 18 years old and undataSex Female. The name is a readable summary and the DCID an identifier; the structured metadata is the authoritative way to inspect the constraints, so do not parse the bracket or the DCID for meaning the metadata provides.

Two more things about constraints:

• Not applicable can be a legitimate constraint value rather than an error or a missing value, and what it means depends on the dimension: in ECLAC’s years-of-education series, undataAveragingMethod Not applicable marks values that are not cross-country averages, while Simple average marks the regional aggregate computed that way.

• The other governed slices of the same family, and the vocabulary a constraint draws its values from, can be listed structurally from the identifier — see Inspecting the graph with the REST API.

Indicator search returns candidate statistical-variable DCIDs, which can then be inspected with get_variable_metadata and queried for observations. The variables published through the UN System Data Commons carry DCIDs beginning with undata/; take them from the search tools’ candidates rather than from memory or from examples written for other Data Commons deployments.

A geographic entity in the graph, also identified by a DCID.

There is no separate place-resolution tool: pass qualified human-readable names in the places parameter of search_indicators (Georgia, Asia for the country; the bare Georgia resolves to the US state), and read the place DCIDs back from dcidNameMappings and placesWithData in the result. A search without places returns no place DCIDs at all.

The search tools’ place parameters (places, parent_place, sample_child_places) take human-readable names, never DCIDs; DCIDs go to the metadata and observation tools. On the current deployment a value the server cannot match — a DCID, or a name it does not know — fails with a 500 quoting a Google Maps legacy-API error. That is a known backend error-handling issue, not a sign that the MCP service is unavailable: retry with a plain English name.

A place the knowledge graph records as contained within a parent geography, at any level of the place hierarchy: the countries within a continent, the countries within a UN region or other geographic grouping, the provinces of a country.

The child-places skill and tools traverse that containment, addressing the children by the parent’s DCID and a child place type. What comes back depends on the data loaded: in the current workflows the children are the countries within a supranational geography, and places below country level resolve but currently carry no observations — see Geographic scope.

Where an observation comes from. A statistical variable may have observations from one or more sources or facets; inspect them as part of qualifying a candidate, before observations are retrieved, interpreted or presented.

Provenance is also an additional check that the series belongs to the expected UN source: every facet of a UN System Data Commons variable names a provenance node under undata/p/ whose source is the United Nations.

One distinct series of observations for a variable, identified by a numeric facet id in metadata and observation responses. A facet is characterised by its provenance, its unit and its observationPeriod, and the metadata response also gives each facet’s date range and observation count (obsCount). Read all of these before retrieving.

In this corpus, different periodicities can produce distinct facets even for the same variable and agency: ILO’s unemployment rate, undata/ilo/UNE_DEAP_RT, carries monthly (P1M), quarterly (P3M) and annual (P1Y) facets, all from undata/p/ILO, and which of them cover a place varies: Chile has all three, Kenya the quarterly and the annual one. The facet the server selects by default is not necessarily the annual one; an observation call made without source_override names the facet it used in sourceMetadata and lists the others under alternativeSources.

Three things are easy to confuse:

• the facet id (9589496361978137601) names the series of observations;

• the provenance node (undata/p/UNICEF) names the dataset it came from;

• the source organization (United Nations, the provenance’s source) names the publisher.

To pick a facet, pass its facet id as source_override on the observation tools; a provenance DCID passed there matches nothing and returns no rows.

How a value is to be read. It belongs to the facet, not to the variable: unit appears on each facet in the metadata response and in sourceMetadata on observation responses, and the numbers returned are already expressed in that unit, with no separate scale or multiplier to apply.

Units are identifiers, and the tools expose no label for them, so the identifier is what you read: Percent is shared with the wider graph, and the rest are UN codes of the form undata/UNIT_MEASURE-<CODE> whose code is readable, such as COUNT_PERSONS, PT_POP (percent of population), RATIO_COUNT_DEATHS_PER_100000_COUNT_POP, CR_USD (US dollars) or INDEX.

A count, a percentage, a rate per N, a ratio, an index and a categorical unit are different measurements and are not interchangeable, and close search candidates often differ only there: UNICEF’s count of people under 18 and UNFPA’s percentage of the population under 18 both answer to “population under 18”. Check the unit before comparing or interpreting near neighbours.

A variable carrying the Boolean unit undata/UNIT_MEASURE-CATEGORY_BINARY_TF holds recorded true/false responses: 1 means the recorded response is yes or true, 0 means no or false. The absence of an observation is not a 0; it means nothing was recorded.

A grouping of related statistical variables. This deployment publishes its own topic hierarchy under the root undata/topic/Root (UN System Data Commons), organised by agency, theme and SDG framework, and the search tools return topics from it. Include topics in a search (include_topics=true) for exploratory questions and for questions that ask for a breakdown.

Two kinds of topic come back:

• A broader topic — a theme, an agency, or a series topic such as Total population — organises available statistical content. In the current server it lists every variable beneath it as one flat memberVariables list while its memberTopics stays empty, so the hierarchy itself — which theme a series sits under, which slices it has — is not visible in search results; Inspecting the graph with the REST API shows how to read it from the UN topic root.

• A terminal topic identifies one governed analytical view: its name states the view (Total population, by Sex, undata/topic/unicef/DM_POP.004), it stands for exactly one peer group (next entry), and its memberVariables are that group’s members that have data for the place the search named. Research patterns shows how to use one.

A governed set of statistical variables from one source series that are intended to be considered together for one analytical or presentation view. In the normal analytical form, all fixed dimensions are held constant and the members vary along one dimension under one governed classification: UNICEF’s Total population, by Sex holds undata/unicef/DM_POP.SEX--F and undata/unicef/DM_POP.SEX--M.

In the graph the group is a StatVarPeerGroup node with a DCID under undata/svpg/, and it is paired one-to-one with a terminal topic: two distinct nodes, a pairing the platform enforces, the topic pointing to exactly one group and the group holding the member variables. The terminal topic is the handle the current MCP normally exposes.

Five qualifications matter when you use one:

• peer groups are series-local in the current UN model, so a group never mixes series, agencies or units;

• a group may contain a single member: the series total is one;

• members do not necessarily partition a total or sum to anything, so membership means comparison, not addition;

• one variable can exceptionally belong to more than one group, when the same value takes part in different governed classifications of one dimension: ILO’s unemployment rate for ages 15 to 24 sits in three age groupings;

• peer groups encode the platform’s governed presentation and analytical views, not every comparison a question might call for.

Being intended for downstream presentation and analysis, a group naturally supports several lines over time, grouped bars, selectable members on a map, or a single headline value; which of these fits is still decided from the data’s coverage, its time span and the question, not from membership. Research patterns shows the workflow and its checks; Inspecting the graph with the REST API the structural lookup from a variable.

A node this deployment uses in common with the wider Data Commons knowledge graph rather than copying it: places and their containment, units such as Percent, classifications, enumeration values, semantic concepts.

Sharing gives common identity and navigation; it does not make any other publisher’s statistics part of the UN System Data Commons. The statistical boundary concerns the governed variables, observations and provenance used in an analysis, not the origin of every reference node — see Statistical scope.

A single value of a statistical variable for a place (or entity combination) at a date, carrying its facet.