GnistAI GnistAI
Log in

Getting Started with UN SDG

UN Sustainable Development Goals — 231 indicators across 17 goals covering poverty, health, education, climate, and inequality for 193 countries.

All Tutorials   |   Overview   |   Playground   |   MCP   |   REST API   |   Home
Economics

Data source: UN Stats SDG API v5

Overview

UN SDG wraps UN Stats SDG API v5, handling authentication, pagination, and rate limits for you. This tutorial covers all 8 tools with working code examples you can copy and run.

Prerequisites

  1. Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
  2. Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config 
{
  "mcpServers": {
    "gnist-unsdg": {
      "url": "https://context.gnist.ai/mcp/unsdg/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (8)

list_sdg_goals

List all 17 UN Sustainable Development Goals. Returns each goal's code (1-17), title, and description. Use the goal code to explore targets and indicators via get_goal_targets. Examples: list_sdg_goals() → All 17 goals (poverty, hunger, health, education, etc.)

curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_sdg_goals", "arguments": {}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_sdg_goals'}},
)
print(resp.json())

get_goal_targets

Get targets and indicators for a specific SDG goal. Returns the goal's targets (e.g. 1.1, 1.2) with their indicators and data series codes. Use series codes with get_sdg_series_data for actual values. Examples: get_goal_targets(1) → Targets for 'No Poverty' (1.1 extreme poverty, 1.2 national poverty...) get_goal_targets(13) → Targets for 'Climate Action'

ParameterTypeRequiredDescription
goal_codeintegerrequiredSDG goal number (1-17). E.g. 1 = No Poverty, 13 = Climate Action.
curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_goal_targets", "arguments": {"goal_code": 1}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'goal_code': 1}, 'name': 'get_goal_targets'}},
)
print(resp.json())

get_sdg_indicator_data

Get observation data for SDG indicators. Returns time-series data for the specified indicators, optionally filtered by country and time period. Each observation includes value, source, geographic area, and any dimension breakdowns (age, sex, location, etc.). Examples: get_sdg_indicator_data(['1.1.1'], [156], 2010, 2023) → China poverty rate 2010-2023 get_sdg_indicator_data(['4.1.1'], [578]) → Norway education completion data get_sdg_indicator_data(['13.2.2']) → All countries' greenhouse gas emissions Returns: Paginated observations with value, source, geo area, time period, and dimensions.

ParameterTypeRequiredDescription
indicator_codeslist[string]requiredIndicator code(s), e.g. ['1.1.1'] for extreme poverty rate.
area_codesanyoptionalGeo area code(s). E.g. [578] for Norway, [840] for USA. Use search_sdg_geo_areas to find codes.
time_startanyoptionalStart year (e.g. 2015).
time_endanyoptionalEnd year (e.g. 2023).
pageintegeroptionalPage number (default 1). (default: 1)
page_sizeintegeroptionalResults per page, max 200 (default 50). (default: 50)
curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_sdg_indicator_data", "arguments": {"indicator_codes": "['1.1.1']"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'indicator_codes': "['1.1.1']"},
            'name': 'get_sdg_indicator_data'}},
)
print(resp.json())

get_sdg_series_data

Get observation data for specific SDG data series. More granular than indicator data — a single indicator may have multiple series with different measurement methodologies. Use get_goal_targets to discover available series codes. Examples: get_sdg_series_data(['SI_POV_DAY1'], [840], 2000, 2023) → US $2.15/day poverty get_sdg_series_data(['EN_ATM_GHGT_AIP'], [578]) → Norway greenhouse gas index Returns: Paginated observations with value, source, and disaggregation dimensions.

ParameterTypeRequiredDescription
series_codeslist[string]requiredSeries code(s), e.g. ['SI_POV_DAY1'] for poverty rate.
area_codesanyoptionalGeo area code(s). E.g. [578] for Norway.
time_startanyoptionalStart year.
time_endanyoptionalEnd year.
pageintegeroptionalPage number. (default: 1)
page_sizeintegeroptionalResults per page, max 200. (default: 50)
curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_sdg_series_data", "arguments": {"series_codes": "['SI_POV_DAY1']"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_codes': "['SI_POV_DAY1']"},
            'name': 'get_sdg_series_data'}},
)
print(resp.json())

search_sdg_geo_areas

Search for SDG geo area codes by name. Returns matching country and region codes that can be used with the indicator and series data tools. Examples: search_sdg_geo_areas('Norway') → [{'code': '578', 'name': 'Norway'}] search_sdg_geo_areas('Africa') → All African regions and sub-regions

ParameterTypeRequiredDescription
querystringrequiredSearch term for country or region name (e.g. 'Norway', 'Africa').
curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_sdg_geo_areas", "arguments": {"query": "'Norway'"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': "'Norway'"}, 'name': 'search_sdg_geo_areas'}},
)
print(resp.json())

get_sdg_series_dimensions

Get available dimensions (disaggregations) for a data series. Shows what breakdowns are available — age groups, sex, location type, reporting type, etc. Useful for understanding what granularity exists before querying data. Examples: get_sdg_series_dimensions('SI_POV_DAY1') → Age, Sex, Reporting Type dimensions

ParameterTypeRequiredDescription
series_codestringrequiredSeries code, e.g. 'SI_POV_DAY1'.
curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_sdg_series_dimensions", "arguments": {"series_code": "'SI_POV_DAY1'"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_code': "'SI_POV_DAY1'"},
            'name': 'get_sdg_series_dimensions'}},
)
print(resp.json())

get_sdg_data_availability

Get which countries and regions have data for a specific series. Useful for checking data coverage before querying — not all series have data for all countries. Examples: get_sdg_data_availability('SI_POV_DAY1') → Countries with poverty data

ParameterTypeRequiredDescription
series_codestringrequiredSeries code, e.g. 'SI_POV_DAY1'.
curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_sdg_data_availability", "arguments": {"series_code": "'SI_POV_DAY1'"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_code': "'SI_POV_DAY1'"},
            'name': 'get_sdg_data_availability'}},
)
print(resp.json())

report_feedback

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: general)
curl -X POST "https://context.gnist.ai/mcp/unsdg/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/unsdg/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use list_sdg_goals to find items, then get_goal_targets to get full details. This two-step pattern is common for exploring data before drilling down.
Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does UN SDG provide?

UN Sustainable Development Goals — 231 indicators across 17 goals covering poverty, health, education, climate, and inequality for 193 countries. It exposes 8 tools: list_sdg_goals, get_goal_targets, get_sdg_indicator_data, get_sdg_series_data, search_sdg_geo_areas, get_sdg_series_dimensions, get_sdg_data_availability, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the UN SDG API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground
Try tools in your browser — no setup required.
Full Reference
Complete docs for all 8 tools.

Related Tutorials

Economic Indicators
Tutorial
BLS (Bureau of Labor Statistics)
Tutorial
DST (Statistics Denmark)
Tutorial
ESCO (Skills & Occupations)
Tutorial
Eurostat
Tutorial
Commodity Prices
Tutorial