get_code_usage
Check whether specific codes have data in a dataflow without running data queries. Get usage status for listed codes or retrieve all used codes per dimension.
Instructions
Efficiently check if specific codes are actually used in a dataflow's data.
This uses the Actual ContentConstraint (if available) to determine which
codes have real data, WITHOUT iterating through data queries. This is
much faster than trial-and-error data requests.
Use cases:
- "Is country code 'FJ' actually used in DF_SDG?"
- "Which indicator codes have data?" (leave codes empty)
- "Are these 5 codes I want to use valid AND have data?"
Args:
dataflow_id: The dataflow to check
codes: Optional list of specific codes to check. If empty, returns all used codes.
dimension_id: Optional dimension to check. If empty, checks all dimensions.
agency_id: The agency (uses session endpoint if not specified)
endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
specific provider for this call only. Defaults to the session's
current endpoint.
Returns:
CodeUsageResult with:
- codes_checked: List of codes with their usage status
- all_used_codes: All codes that have data (by dimension)
- summary: Counts of used/unused codes
Examples:
>>> get_code_usage("DF_SDG", codes=["FJ", "WS", "XX"], dimension_id="GEO_PICT")
# Checks if Fiji, Samoa, and "XX" have SDG data
>>> get_code_usage("DF_SDG", dimension_id="INDICATOR")
# Returns all indicator codes that actually have data
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| codes | No | ||
| endpoint | No | ||
| agency_id | No | ||
| dataflow_id | Yes | ||
| dimension_id | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | Summary counts: total_checked, used, unused | |
| dataflow_id | Yes | Dataflow checked | |
| dimension_id | No | Dimension checked (if specific) | |
| codes_checked | Yes | Usage status for each code | |
| constraint_id | No | Actual constraint used | |
| all_used_codes | No | All codes with actual data per dimension (if no specific codes requested) | |
| api_calls_made | No | Number of API calls made | |
| interpretation | Yes | Human-readable explanation | |
| discovery_level | No | Discovery workflow level | code_usage |