worldbank-mcp-server

List all 21 World Bank thematic topics (Economy & Growth, Health, Education, and others) with descriptions. Use it to browse the indicator space by theme or to find a topic_id for worldbank_search_indicators.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "topics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Topic ID for use in worldbank_search_indicators."
          },
          "name": {
            "type": "string",
            "description": "Topic name."
          },
          "sourceNote": {
            "type": "string",
            "description": "Brief description of the topic."
          }
        },
        "required": [
          "id",
          "name",
          "sourceNote"
        ],
        "additionalProperties": false,
        "description": "A thematic topic entry."
      },
      "description": "All 21 World Bank thematic topics."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "topics"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List the 70+ World Bank data sources (datasets), such as World Development Indicators, International Debt Statistics, and Doing Business. Returns source IDs and names for use as source_id in worldbank_search_indicators, one page at a time.

{
  "type": "object",
  "properties": {
    "page": {
      "default": 1,
      "description": "Pagination page number (1-based).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Results per page (default: server default, max: 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Source ID for use in worldbank_search_indicators."
          },
          "name": {
            "type": "string",
            "description": "Dataset name."
          },
          "code": {
            "type": "string",
            "description": "Short dataset code."
          },
          "lastUpdated": {
            "type": "string",
            "description": "Date of last data update (YYYY-MM-DD or empty)."
          },
          "dataAvailability": {
            "type": "string",
            "description": "Data availability status."
          },
          "metadataAvailability": {
            "type": "string",
            "description": "Metadata availability status."
          },
          "concepts": {
            "type": "string",
            "description": "Number of concepts (variables) in this source."
          }
        },
        "required": [
          "id",
          "name",
          "code",
          "lastUpdated",
          "dataAvailability",
          "metadataAvailability",
          "concepts"
        ],
        "additionalProperties": false,
        "description": "A World Bank data source entry."
      },
      "description": "World Bank data sources for this page."
    },
    "totalCount": {
      "type": "number",
      "description": "Total number of sources."
    },
    "currentPage": {
      "type": "number",
      "description": "Page number requested — past totalPages when the request ran off the end."
    },
    "totalPages": {
      "type": "number",
      "description": "Total number of pages."
    },
    "notice": {
      "description": "Context for an empty page: the page range that exists when the requested page is past the end.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "sources",
        "totalCount",
        "currentPage",
        "totalPages"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List countries and regional aggregates with metadata: ISO codes, region, income level, capital, and coordinates. Filter by region code (e.g. EAS, SSF, NAC) and income level (LIC, LMC, UMC, HIC). Aggregate entries are excluded by default, leaving individual countries only; set include_aggregates=true to also return region, income group, and world aggregate entities.

{
  "type": "object",
  "properties": {
    "region": {
      "description": "Filter by World Bank region code. Valid codes: EAS (East Asia & Pacific), ECS (Europe & Central Asia), LCN (Latin America & Caribbean), MEA (Middle East & North Africa), NAC (North America), SAS (South Asia), SSF (Sub-Saharan Africa).",
      "type": "string"
    },
    "income_level": {
      "description": "Filter by income group code: LIC (Low income), LMC (Lower middle income), UMC (Upper middle income), HIC (High income).",
      "type": "string"
    },
    "include_aggregates": {
      "default": false,
      "description": "When true, includes regional, income-group, and world aggregate entries alongside individual countries. Default false (individual countries only).",
      "type": "boolean"
    },
    "page": {
      "default": 1,
      "description": "Pagination page number (1-based).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Results per page (default: server default, max: 300).",
      "type": "integer",
      "minimum": 1,
      "maximum": 300
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "countries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Country or aggregate ID (ISO2 or WB aggregate code)."
          },
          "iso2": {
            "type": "string",
            "description": "ISO2 country code."
          },
          "name": {
            "type": "string",
            "description": "Country or aggregate name."
          },
          "region": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Region code."
              },
              "name": {
                "type": "string",
                "description": "Region name."
              }
            },
            "required": [
              "id",
              "name"
            ],
            "additionalProperties": false,
            "description": "World Bank region this country belongs to."
          },
          "incomeLevel": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Income level code."
              },
              "name": {
                "type": "string",
                "description": "Income level name."
              }
            },
            "required": [
              "id",
              "name"
            ],
            "additionalProperties": false,
            "description": "World Bank income classification."
          },
          "lendingType": {
            "type": "string",
            "description": "World Bank lending type classification."
          },
          "capitalCity": {
            "type": "string",
            "description": "Capital city name (empty for aggregates)."
          },
          "longitude": {
            "type": "string",
            "description": "Capital longitude (empty for aggregates)."
          },
          "latitude": {
            "type": "string",
            "description": "Capital latitude (empty for aggregates)."
          },
          "isAggregate": {
            "type": "boolean",
            "description": "True when this entry is a regional or income-group aggregate rather than an individual country."
          }
        },
        "required": [
          "id",
          "iso2",
          "name",
          "region",
          "incomeLevel",
          "lendingType",
          "capitalCity",
          "longitude",
          "latitude",
          "isAggregate"
        ],
        "additionalProperties": false,
        "description": "A country or aggregate entry."
      },
      "description": "Countries (and optionally aggregates) matching the filters."
    },
    "totalCount": {
      "type": "number",
      "description": "Total matching entries before pagination (includes aggregates if include_aggregates=true)."
    },
    "currentPage": {
      "type": "number",
      "description": "Page number requested — past totalPages when the request ran off the end."
    },
    "totalPages": {
      "type": "number",
      "description": "Total number of pages."
    },
    "notice": {
      "description": "Context for an empty page: which filters matched nothing, or the page range that exists when the requested page is past the end.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_filter`: An invalid region or income_level code was provided. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_filter"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "countries",
        "totalCount",
        "currentPage",
        "totalPages"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch metadata for one country or aggregate entity: ISO codes, region, income level, lending type, capital, and coordinates. Accepts an ISO2 code (US, DE), an ISO3 code (USA, DEU), or a World Bank aggregate code (EAS, HIC, WLD); "all" and lists of codes are rejected. Use worldbank_list_countries to browse valid codes.

{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{2,3}$",
      "description": "One country code. Accepts ISO2 (US), ISO3 (USA), or aggregate code (EAS, HIC, WLD) — not \"all\" or a list of codes. Use worldbank_list_countries to browse valid codes."
    }
  },
  "required": [
    "country_code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Country or aggregate ID."
    },
    "iso2": {
      "type": "string",
      "description": "ISO2 country code."
    },
    "name": {
      "type": "string",
      "description": "Country or aggregate name."
    },
    "region": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Region code."
        },
        "name": {
          "type": "string",
          "description": "Region name."
        }
      },
      "required": [
        "id",
        "name"
      ],
      "additionalProperties": false,
      "description": "World Bank region this country belongs to."
    },
    "incomeLevel": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Income level code."
        },
        "name": {
          "type": "string",
          "description": "Income level name."
        }
      },
      "required": [
        "id",
        "name"
      ],
      "additionalProperties": false,
      "description": "World Bank income classification."
    },
    "lendingType": {
      "type": "string",
      "description": "World Bank lending type classification."
    },
    "capitalCity": {
      "type": "string",
      "description": "Capital city name (empty for aggregates)."
    },
    "longitude": {
      "type": "string",
      "description": "Capital longitude (empty for aggregates)."
    },
    "latitude": {
      "type": "string",
      "description": "Capital latitude (empty for aggregates)."
    },
    "isAggregate": {
      "type": "boolean",
      "description": "True when this entry is a regional or income-group aggregate."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `country_not_found`: The country code does not exist in the World Bank API. `multiple_countries`: The code is \"all\", or another selector the World Bank resolves to more than one country. Other values are possible when a failure originates below the handler.",
              "examples": [
                "country_not_found",
                "multiple_countries"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "id",
        "iso2",
        "name",
        "region",
        "incomeLevel",
        "lendingType",
        "capitalCity",
        "longitude",
        "latitude",
        "isAggregate"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Search the 29,500+ World Bank indicator catalog by keyword, topic, or source, returning indicator IDs and metadata for worldbank_get_data. Provide at least one of query, topic_id, or source_id; a topic and a source together narrow to indicators in both. A keyword query matches every term against indicator ID, name, and description, in any word order, across the whole catalog or the whole selected topic or source; punctuation is ignored, so the query needs at least one letter or digit. Exact ID or name matches rank first, then whole-phrase matches, then other ID/name matches, then description-only matches. Each indicator ID appears once, even where the catalog publishes it under two sources. Find topic IDs with worldbank_list_topics and source IDs with worldbank_list_sources.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Keyword search terms — an indicator name, ID, or any words from either (e.g. \"GDP per capita\", \"NY.GDP.MKTP.CD\", \"CO2 emissions\"). Every term must match; punctuation is ignored, so the query needs at least one letter or digit. At least one of query, topic_id, or source_id must be provided.",
      "type": "string"
    },
    "topic_id": {
      "description": "Filter by topic ID (e.g. \"1\" for Agriculture, \"3\" for Economy & Growth). Use worldbank_list_topics to browse valid IDs.",
      "type": "string",
      "pattern": "^\\s*\\d*\\s*$"
    },
    "source_id": {
      "description": "Filter by data source ID (e.g. \"2\" for World Development Indicators). Use worldbank_list_sources to browse valid IDs.",
      "type": "string",
      "pattern": "^\\s*\\d*\\s*$"
    },
    "page": {
      "default": 1,
      "description": "Pagination page number (1-based).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Results per page (default: server default, max: 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "indicators": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Indicator ID (e.g. NY.GDP.PCAP.CD). Use as indicator_id in worldbank_get_data."
          },
          "name": {
            "type": "string",
            "description": "Indicator name."
          },
          "sourceId": {
            "type": "string",
            "description": "Source dataset ID."
          },
          "sourceName": {
            "type": "string",
            "description": "Source dataset name."
          },
          "sourceNote": {
            "type": "string",
            "description": "Brief indicator description."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Topic ID."
                },
                "name": {
                  "type": "string",
                  "description": "Topic name."
                }
              },
              "required": [
                "id",
                "name"
              ],
              "additionalProperties": false,
              "description": "A thematic topic entry."
            },
            "description": "Thematic topics this indicator belongs to."
          }
        },
        "required": [
          "id",
          "name",
          "sourceId",
          "sourceName",
          "sourceNote",
          "topics"
        ],
        "additionalProperties": false,
        "description": "A matching indicator with metadata."
      },
      "description": "Matching indicators for this page."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "query": {
          "description": "Trimmed keyword query sent to the search, omitted when none was given.",
          "type": "string"
        },
        "topicId": {
          "description": "Topic ID the results were scoped to, omitted when none was given.",
          "type": "string"
        },
        "sourceId": {
          "description": "Source ID the results were scoped to, omitted when none was given.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "The effective search parameters, field by field — confirms which filter combination produced these results without parsing the effectiveQuery string."
    },
    "effectiveQuery": {
      "description": "Active filters echoed: keyword, topic ID, and/or source ID that were applied.",
      "type": "string"
    },
    "totalCount": {
      "type": "number",
      "description": "Total matching indicators before pagination."
    },
    "currentPage": {
      "type": "number",
      "description": "Current page number."
    },
    "totalPages": {
      "type": "number",
      "description": "Total number of pages."
    },
    "notice": {
      "description": "Recovery hint when no indicators matched — suggests how to broaden the search.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `missing_filter`: None of query, topic_id, or source_id were provided. `invalid_filter`: The topic_id or source_id does not exist upstream. `empty_query`: The query contains no letters or digits once punctuation is ignored. Other values are possible when a failure originates below the handler.",
              "examples": [
                "missing_filter",
                "invalid_filter",
                "empty_query"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "indicators",
        "appliedFilters",
        "totalCount",
        "currentPage",
        "totalPages"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch metadata for one World Bank indicator by ID: name, description, unit, source dataset, source organization, and thematic topics. Use worldbank_search_indicators to find the ID when only the concept is known; "all" and lists of IDs are rejected.

{
  "type": "object",
  "properties": {
    "indicator_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]+$",
      "description": "One indicator code (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL) — not \"all\" or a list of codes. Use worldbank_search_indicators to find valid IDs."
    }
  },
  "required": [
    "indicator_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Indicator ID."
    },
    "name": {
      "type": "string",
      "description": "Indicator name."
    },
    "unit": {
      "type": "string",
      "description": "Unit of measurement (empty when not specified)."
    },
    "sourceId": {
      "type": "string",
      "description": "Source dataset ID."
    },
    "sourceName": {
      "type": "string",
      "description": "Source dataset name."
    },
    "sourceNote": {
      "type": "string",
      "description": "Detailed indicator description from the source."
    },
    "sourceOrganization": {
      "type": "string",
      "description": "Organization that collects or publishes this data."
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Topic ID."
          },
          "name": {
            "type": "string",
            "description": "Topic name."
          }
        },
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": false,
        "description": "A thematic topic entry."
      },
      "description": "Thematic topics this indicator belongs to."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `indicator_not_found`: The indicator ID does not exist in the World Bank API. `multiple_indicators`: The ID is \"all\", or another selector the World Bank resolves to more than one indicator. Other values are possible when a failure originates below the handler.",
              "examples": [
                "indicator_not_found",
                "multiple_indicators"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "id",
        "name",
        "unit",
        "sourceId",
        "sourceName",
        "sourceNote",
        "sourceOrganization",
        "topics"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Query World Bank indicator values for one or more countries across a time range — the primary data-access tool; find indicator_id values with worldbank_search_indicators. Observations carry a null value where data is not available for a country×year cell, which is common for sparse series. Set either date_range (historical analysis) or mrv (most recent N values), not both. For "all" countries, page through the results (per_page up to 1000), since the API returns several hundred entries per indicator. Indicators the standard data endpoint does not serve — WDI Database Archives, PEFA, ICP, GDLD, International Debt Statistics: DSSI, Food Prices for Nutrition — are answered from their own dataset instead; the response then carries sourceScoped, naming that dataset and the release, classification, sector, or counterpart area applied (see dimension_value), because those values can be archived or superseded figures rather than current ones.

{
  "type": "object",
  "properties": {
    "indicator_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]+$",
      "description": "One indicator code to query (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL) — not \"all\" or a list of codes. Use worldbank_search_indicators to find valid IDs."
    },
    "countries": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "[^\\s;,]",
          "description": "A single country code, a comma- or semicolon-separated list, or \"all\"."
        },
        {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string",
            "description": "A country code."
          },
          "description": "An array of country codes."
        }
      ],
      "description": "Country codes. Accepts: ISO2 (US, CN), ISO3 (USA, CHN), regional aggregate codes (EAS, LCN, MEA, SAS, SSF, ECS, NAC), income group codes (HIC, UMC, LMC, LIC), world code (WLD), or \"all\" on its own for every entry (use pagination). Pass a single code, an array, or one string separated by commas or semicolons. At least one code is required — an empty value is rejected rather than treated as \"all\"."
    },
    "date_range": {
      "description": "Time window to filter observations to. Accepts a whole year (`2020`), a quarter (`2020Q1`), or a month (`2020M03`), or a range of two periods of the same type separated by a colon, earliest first (`2010:2023`, `2020Q1:2021Q4`, `2020M01:2020M06`); a range running latest first is rejected. A window and an observation match whenever the periods overlap, so a year window also selects the quarters and months inside it. A window covering no part of the series returns zero observations rather than the full series. Mutually exclusive with mrv.",
      "type": "string",
      "pattern": "^\\s*(?:\\d{4}(?::\\d{4})?|\\d{4}[Qq][1-4](?::\\d{4}[Qq][1-4])?|\\d{4}[Mm](?:0[1-9]|1[0-2])(?::\\d{4}[Mm](?:0[1-9]|1[0-2]))?)?\\s*$"
    },
    "mrv": {
      "description": "Return the N most recent periods (1–100) holding a value for any requested country, clamped to the length of the series. Every requested country comes back at those periods, null where it has no value there rather than with its own older values. Rows are mrv × countries, so page through them with per_page. Mutually exclusive with date_range.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "dimension_value": {
      "description": "For indicators answered from their own dataset (the response carries sourceScoped), the id of the value of that dataset's extra dimension to query, matched case-insensitively: a WDI Database Archives release (\"202503\"), an ICP or Food Prices for Nutrition classification (\"PPPGlob\", \"FPN 5.0\"), a GDLD sector (\"WHT\"), or an International Debt Statistics counterpart area (\"265\"). Omit it for the default, which sourceScoped.dimension reports: the only value when the dataset has one, \"WLD\" (World) for counterpart areas, the newest WDI Database Archives release holding data for the requested countries and periods (the newest release when none does), or otherwise every value with each row labelled. A value the dataset does not list is rejected with the valid ids, and a value for an indicator the standard data endpoint serves is rejected too.",
      "type": "string"
    },
    "page": {
      "default": 1,
      "description": "Pagination page number (1-based).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Results per page (default: server default, max: 1000). Use higher values for \"all\" country queries.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "indicator_id",
    "countries"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "countryCode": {
            "type": "string",
            "description": "ISO2 country code (or aggregate code)."
          },
          "countryIso3": {
            "type": "string",
            "description": "ISO3 country code (empty for some aggregates)."
          },
          "countryName": {
            "type": "string",
            "description": "Country or aggregate name."
          },
          "date": {
            "type": "string",
            "description": "Period of observation: a year (2020), quarter (2020Q1), or month (2020M03)."
          },
          "value": {
            "description": "Indicator value. Null when data is not available for this country×year cell.",
            "type": [
              "number",
              "null"
            ]
          },
          "obsStatus": {
            "type": "string",
            "description": "Observation status code (empty string when no special status; non-empty values signal data quality notes)."
          },
          "isAggregate": {
            "type": "boolean",
            "description": "True when this row is a regional or income-group aggregate rather than an individual country."
          },
          "dimension": {
            "description": "The value of the dataset's extra dimension (sourceScoped.dimension.concept) this row belongs to. Present on source-scoped rows from a dataset that has one.",
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Dimension value id, e.g. \"202503\"."
              },
              "label": {
                "type": "string",
                "description": "Dimension value label, e.g. \"2025 Mar\"."
              }
            },
            "required": [
              "id",
              "label"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "countryCode",
          "countryIso3",
          "countryName",
          "date",
          "value",
          "obsStatus",
          "isAggregate"
        ],
        "additionalProperties": false,
        "description": "A single country×period observation."
      },
      "description": "Indicator observations for this page. Null values are common for sparse series."
    },
    "sourceScoped": {
      "description": "Present only when the standard data endpoint does not serve the indicator and its catalog source served the values instead. Absent for indicators the standard endpoint serves.",
      "type": "object",
      "properties": {
        "sourceId": {
          "type": "string",
          "description": "ID of the World Bank data source that served the values."
        },
        "sourceName": {
          "type": "string",
          "description": "Name of that data source, e.g. \"WDI Database Archives\"."
        },
        "dimension": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "concept": {
                  "type": "string",
                  "description": "The extra dimension: Version, Classification, Sector, or Counterpart-Area."
                },
                "selection": {
                  "type": "string",
                  "enum": [
                    "requested",
                    "only_value",
                    "world_total",
                    "newest_with_data",
                    "newest",
                    "every_value"
                  ],
                  "description": "How the value was chosen: requested (dimension_value), only_value (the only one the dataset lists), world_total (WLD, all counterpart areas), newest_with_data (newest release holding a value for the requested countries and periods), newest (newest release; none holds a value in that scope), or every_value (no single value; each row carries its own)."
                },
                "id": {
                  "description": "Applied value id; null for every_value.",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "label": {
                  "description": "Applied value label; null for every_value.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "concept",
                "selection",
                "id",
                "label"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ],
          "description": "The dimension value applied; null when the dataset has no extra dimension."
        },
        "note": {
          "type": "string",
          "description": "States that the values came from the source-scoped data API rather than the standard World Bank data endpoint, and may be archived or superseded figures."
        }
      },
      "required": [
        "sourceId",
        "sourceName",
        "dimension",
        "note"
      ],
      "additionalProperties": false
    },
    "indicator": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Indicator ID echoed for chaining context."
        },
        "name": {
          "type": "string",
          "description": "Indicator name."
        }
      },
      "required": [
        "id",
        "name"
      ],
      "additionalProperties": false,
      "description": "Indicator metadata echoed from the response."
    },
    "nullCount": {
      "type": "number",
      "description": "Count of null values on this page — indicates data sparsity for the requested filter."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "indicatorId": {
          "type": "string",
          "description": "Indicator ID queried."
        },
        "countries": {
          "type": "string",
          "description": "Country codes as sent to the API — array elements and comma- or semicolon-separated strings are split and rejoined with semicolons, so this shows the normalized value."
        },
        "dateRange": {
          "description": "Date window applied, omitted when none was requested.",
          "type": "string"
        },
        "mrv": {
          "description": "Most-recent-values count applied, omitted when none was requested.",
          "type": "number"
        },
        "dimensionValue": {
          "description": "dimension_value as requested, omitted when none was given.",
          "type": "string"
        },
        "page": {
          "type": "number",
          "description": "Page number requested."
        },
        "perPage": {
          "type": "number",
          "description": "Results per page used, including the server default."
        }
      },
      "required": [
        "indicatorId",
        "countries",
        "page",
        "perPage"
      ],
      "additionalProperties": false,
      "description": "The effective parameters sent to the World Bank API — confirms country code normalization and which filters were in force for these observations."
    },
    "totalCount": {
      "type": "number",
      "description": "Total observations before pagination."
    },
    "currentPage": {
      "type": "number",
      "description": "Page number requested — past totalPages when the request ran off the end."
    },
    "totalPages": {
      "type": "number",
      "description": "Total number of pages."
    },
    "notice": {
      "description": "Recovery hint for an empty result set — how to broaden the query when nothing matched, or the page range that exists when the requested page is past the end — and, for source-scoped data, the requested country codes the serving dataset publishes nothing for.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_params`: Both date_range and mrv are provided simultaneously. `mixed_all_selector`: countries combines \"all\" with one or more country codes. `reversed_date_range`: date_range names a range whose first period comes after its second. `multiple_indicators`: The indicator ID is \"all\", which selects every indicator rather than one. `indicator_not_found`: The indicator ID does not exist. `indicator_not_queryable`: The standard data endpoint does not serve the indicator, and no catalog source can serve it through the source-scoped data API instead — the catalog no longer lists the ID, the catalog lookup failed, or the source is not organized by country, series, and time plus at most one further dimension. `unknown_dimension_value`: dimension_value is not a value the indicator's dataset lists for its extra dimension. `dimension_not_applicable`: dimension_value is given for an indicator the standard data endpoint serves, or whose dataset has no dimension beyond country, series, and time. `source_scope_too_large`: A source-scoped query would read more rows (countries × periods × unpinned dimension values) than one request allows. `country_not_found`: One or more country codes are invalid. `indicator_and_country_not_found`: The indicator ID and the country codes are both invalid. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_params",
                "mixed_all_selector",
                "reversed_date_range",
                "multiple_indicators",
                "indicator_not_found",
                "indicator_not_queryable",
                "unknown_dimension_value",
                "dimension_not_applicable",
                "source_scope_too_large",
                "country_not_found",
                "indicator_and_country_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "data",
        "indicator",
        "nullCount",
        "appliedFilters",
        "totalCount",
        "currentPage",
        "totalPages"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Query poverty and inequality estimates from the World Bank Poverty and Inequality Platform (PIP) for one or more countries. Returns the poverty headcount ratio, poverty gap, and poverty severity at any poverty line, plus mean and median welfare and population. Use it for inequality and distribution questions too — survey-based rows carry the Gini coefficient, mean log deviation, polarization, and the ten decile income/consumption shares, because PIP returns poverty and inequality in the same row. PIP is a separate dataset from the WDI series worldbank_get_data reads: it measures welfare in PPP dollars per person per day, at a PPP vintage ppp_version selects, and covers individual economies only, so regional and income-group aggregate codes are not accepted. Every row reports how it was produced. estimationType "survey" rows carry the full inequality block; "interpolation", "extrapolation", and "CMD estimation" rows are gap-filled estimates for years no survey covers, and their gini, mld, polarization, and decileShares are null — a documented gap in the source data, not an error.

{
  "type": "object",
  "properties": {
    "countries": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "[^\\s;,]",
          "description": "A single country code, a comma-separated list, or \"all\"."
        },
        {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string",
            "description": "A country code."
          },
          "description": "An array of country codes."
        }
      ],
      "description": "Country codes. PIP identifies economies by ISO3 code (IND, USA, BRA); \"all\" returns every economy it covers. Pass a single code, an array, or one string separated by commas or semicolons. Regional, income-group, and world aggregate codes (WLD, SSF, HIC) are not served by this dataset — query the individual economies instead."
    },
    "year": {
      "description": "Reporting year to return. A four-digit year (2022), \"all\" for the full history, or \"MRV\" for the most recent year available. Omitted behaves as \"all\". PIP coverage starts in 1963 and runs to the current year.",
      "type": "string",
      "pattern": "^\\s*(?:\\d{4}|all|MRV)?\\s*$"
    },
    "poverty_line": {
      "description": "Poverty line in PPP dollars per person per day, at the applied PPP vintage — any threshold, not only the published ones. Omitted uses the international poverty line for that vintage, so the applied value is echoed back on every row as povertyLine rather than assumed here. The poverty line does not affect the inequality fields, which describe the whole distribution.",
      "type": "number",
      "minimum": 0,
      "maximum": 2700
    },
    "welfare_type": {
      "description": "Restrict results to one welfare measure. Surveys measure either income or consumption and the two are not directly comparable, so a cross-country comparison is safer pinned to one. Omitted returns whichever each economy publishes, and both where an economy publishes both — thirty-five do, and those return two rows per year.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "enum": [
            "income",
            "consumption"
          ],
          "description": "Restrict to surveys measuring income, or to those measuring consumption."
        }
      ]
    },
    "reporting_level": {
      "description": "Restrict results to one reporting level. Most economies publish a national figure only; ten publish a split and return an extra row per year for it, China with all three levels and the rest pairing national with either urban or rural. Every row states its own reportingLevel.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "enum": [
            "national",
            "urban",
            "rural"
          ],
          "description": "Restrict to the national, urban, or rural estimate."
        }
      ]
    },
    "ppp_version": {
      "description": "PPP vintage to express every dollar figure in — the poverty line, mean, and median — as a four-digit year (\"2021\", \"2017\"). It must be one of the vintages PIP's current data release is published at; any other value fails with the available vintages named. Omitted uses the newest vintage of that release. The vintage and release applied are echoed as appliedFilters.pppVersion and appliedFilters.releaseVersion.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}$",
          "description": "A PPP vintage year."
        }
      ]
    },
    "fill_gaps": {
      "default": true,
      "description": "When true (the default), any year the surveys do not cover falls back to PIP's own estimate for it instead of being left out — so a single-year query still answers, and a full-history query returns a row per year rather than only the survey years. Those fallback rows carry no inequality data. Set false to return survey-derived rows only, accepting an empty result for years no survey covers.",
      "type": "boolean"
    },
    "page": {
      "default": 1,
      "description": "Pagination page number (1-based).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Results per page (default: server default, max: 1000). \"all\" countries across \"all\" years runs to several thousand rows. One page holds at most 70 estimates, which keeps a response within about 50 KB; a larger value, the server default included, is reduced to that cap, disclosed in notice, and echoed as appliedFilters.perPage, and totalPages is counted at the reduced size.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "countries"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "estimates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "countryCode": {
            "type": "string",
            "description": "ISO3 country code."
          },
          "countryName": {
            "type": "string",
            "description": "Economy name."
          },
          "regionCode": {
            "type": "string",
            "description": "PIP region code (e.g. SAS, NAC, SSA)."
          },
          "regionName": {
            "type": "string",
            "description": "PIP region name."
          },
          "reportingYear": {
            "type": "number",
            "description": "Calendar year the estimate reports on."
          },
          "reportingLevel": {
            "type": "string",
            "description": "Coverage of this estimate: national, urban, or rural."
          },
          "welfareType": {
            "type": "string",
            "description": "Whether the underlying survey measures income or consumption. The two are not directly comparable across economies."
          },
          "povertyLine": {
            "type": "number",
            "description": "Poverty line the poverty measures were computed at, in PPP dollars per person per day, as applied upstream."
          },
          "headcount": {
            "description": "Share of the population below the poverty line, as a fraction (0.0814 = 8.14%).",
            "type": [
              "number",
              "null"
            ]
          },
          "povertyGap": {
            "description": "Mean shortfall below the poverty line across the whole population, as a fraction of the line — depth of poverty, not just its incidence.",
            "type": [
              "number",
              "null"
            ]
          },
          "povertySeverity": {
            "description": "Squared poverty gap, weighting the poorest most heavily — inequality among those below the line.",
            "type": [
              "number",
              "null"
            ]
          },
          "watts": {
            "description": "Watts index, a distribution-sensitive measure.",
            "type": [
              "number",
              "null"
            ]
          },
          "mean": {
            "description": "Mean daily welfare per person in PPP dollars.",
            "type": [
              "number",
              "null"
            ]
          },
          "median": {
            "description": "Median daily welfare per person in PPP dollars.",
            "type": [
              "number",
              "null"
            ]
          },
          "gini": {
            "description": "Gini coefficient of the welfare distribution, 0 (perfect equality) to 1. Null on gap-filled rows — see estimationType.",
            "type": [
              "number",
              "null"
            ]
          },
          "mld": {
            "description": "Mean log deviation, an inequality measure. Null on gap-filled rows.",
            "type": [
              "number",
              "null"
            ]
          },
          "polarization": {
            "description": "Wolfson polarization index. Null on gap-filled rows.",
            "type": [
              "number",
              "null"
            ]
          },
          "decileShares": {
            "anyOf": [
              {
                "minItems": 10,
                "maxItems": 10,
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Share of total income or consumption held by each decile, poorest first, summing to 1. Null on gap-filled rows."
          },
          "population": {
            "description": "Population the estimate covers — multiply by headcount for the number of people below the line.",
            "type": [
              "number",
              "null"
            ]
          },
          "surveyYear": {
            "description": "Year of the survey behind the estimate, fractional when the survey spans a fiscal year (2022.58). Null on gap-filled rows, which trace to no single survey.",
            "type": [
              "number",
              "null"
            ]
          },
          "surveyAcronym": {
            "type": "string",
            "description": "Short name of the underlying survey (empty on gap-filled rows and where PIP publishes none)."
          },
          "surveyComparability": {
            "description": "PIP's series comparability code within the economy: 0 is its oldest comparable series and the code steps up each time comparability breaks, so two survey rows of one economy compare over time only when they share it. Null on gap-filled rows.",
            "type": [
              "number",
              "null"
            ]
          },
          "comparableSpell": {
            "description": "The span of years the comparable series behind this row covers, as PIP labels it (\"2022\", \"2011 - 2022\"). Null on gap-filled rows.",
            "type": [
              "string",
              "null"
            ]
          },
          "estimationType": {
            "type": "string",
            "description": "How the row was produced: \"survey\" carries the full inequality block; \"interpolation\", \"extrapolation\", and \"CMD estimation\" are gap-filled and carry none. The last is what PIP publishes for economies it has no survey for at all."
          },
          "isInterpolated": {
            "type": "boolean",
            "description": "True on the interpolated and extrapolated rows. Read estimationType instead of relying on this alone — a \"CMD estimation\" row is also gap-filled but reports false here."
          }
        },
        "required": [
          "countryCode",
          "countryName",
          "regionCode",
          "regionName",
          "reportingYear",
          "reportingLevel",
          "welfareType",
          "povertyLine",
          "headcount",
          "povertyGap",
          "povertySeverity",
          "watts",
          "mean",
          "median",
          "gini",
          "mld",
          "polarization",
          "decileShares",
          "population",
          "surveyYear",
          "surveyAcronym",
          "surveyComparability",
          "comparableSpell",
          "estimationType",
          "isInterpolated"
        ],
        "additionalProperties": false,
        "description": "One country × year × reporting-level × welfare-type estimate."
      },
      "description": "Poverty and inequality estimates for this page, ordered by country, year, reporting level, then welfare type."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "countries": {
          "type": "string",
          "description": "Country codes as sent to PIP — arrays and semicolon-separated input are normalized to a comma-joined list, so this shows the value actually queried."
        },
        "year": {
          "description": "Year filter applied, omitted when none was requested.",
          "type": "string"
        },
        "povertyLine": {
          "description": "Poverty line requested, omitted when the upstream default was used — in which case the applied value is on every row as povertyLine.",
          "type": "number"
        },
        "welfareType": {
          "description": "Welfare-type filter applied, omitted when none.",
          "type": "string"
        },
        "reportingLevel": {
          "description": "Reporting-level filter applied, omitted when none.",
          "type": "string"
        },
        "pppVersion": {
          "type": "string",
          "description": "PPP vintage every dollar figure in these estimates is expressed in, whether requested or resolved as the newest vintage of the release."
        },
        "releaseVersion": {
          "type": "string",
          "description": "PIP data release the estimates come from, as its YYYYMMDD stamp — the newest release PIP lists. Survey and gap-filled rows share it."
        },
        "fillGaps": {
          "type": "boolean",
          "description": "Whether gap-filling was permitted for this query, including the server default of true."
        },
        "page": {
          "type": "number",
          "description": "Page number requested."
        },
        "perPage": {
          "type": "number",
          "description": "Results per page actually served — the requested size or server default, reduced to the page cap when larger. totalPages is counted at this size."
        },
        "requestedPerPage": {
          "description": "Page size asked for, requested or server default, present only when it exceeded the page cap and perPage was reduced.",
          "type": "number"
        }
      },
      "required": [
        "countries",
        "pppVersion",
        "releaseVersion",
        "fillGaps",
        "page",
        "perPage"
      ],
      "additionalProperties": false,
      "description": "The effective parameters sent to PIP — confirms country code normalization and which filters were in force for these estimates."
    },
    "totalCount": {
      "type": "number",
      "description": "Total estimates before pagination."
    },
    "currentPage": {
      "type": "number",
      "description": "Page number requested — past totalPages when the request ran off the end."
    },
    "totalPages": {
      "type": "number",
      "description": "Total number of pages."
    },
    "notice": {
      "description": "Context for an empty result set, for a page past the end of the results, for a page size reduced to the page cap, or for a result carrying gap-filled rows with no inequality data.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `country_not_found`: PIP does not recognize one or more of the country codes. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `ppp_version_unavailable`: ppp_version names a PPP vintage PIP's current data release is not published at. `upstream_unavailable`: PIP answered with a server error, which an aggregate country code also produces. Other values are possible when a failure originates below the handler.",
              "examples": [
                "country_not_found",
                "invalid_parameter",
                "ppp_version_unavailable",
                "upstream_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "estimates",
        "appliedFilters",
        "totalCount",
        "currentPage",
        "totalPages"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Search the World Bank lending portfolio — the individual loans, credits, and grants the Bank finances — by free text, country, region, status, and board approval date. Returns the project ID, name, borrowing country, region, status, board approval and closing dates, total commitment in USD, financing instrument, major sectors, and a link to the project page. This is the operations catalogue, not the statistics catalogue: use it for "what is the World Bank funding in Kenya", "which climate adaptation projects are active", or "how much was committed to education in South Asia since 2020". For development statistics and time series, use worldbank_search_indicators and worldbank_get_data instead. Countries are identified by ISO2 code here (BR, IN, ZA), which is the one place this server departs from the ISO3 codes its other tools take — worldbank_get_country reports a country's iso2 field for either form, and multi-country operations carry a World Bank regional code such as 3A instead. Every filter is an exact match upstream and combines with the others by AND, so a narrow search can legitimately return nothing; when it does, the response says whether the country codes matched anything on their own.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search across project names, abstracts, and objectives. Every word must appear, so extra words narrow the result. Omit to browse the portfolio by filter alone, newest board approvals first.",
      "type": "string"
    },
    "countries": {
      "description": "Borrowing countries, by the two-character code this API keys on: ISO2 for an economy (BR), or a World Bank regional code for a multi-country operation (3A for Africa, 4E for East Asia and Pacific). Several codes are combined as OR — a project matching any of them is returned. Omit for every country.",
      "anyOf": [
        {
          "type": "string",
          "description": "A single two-character code, or a comma- or semicolon-separated list of them."
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "description": "A two-character country code."
          },
          "description": "An array of two-character codes."
        }
      ]
    },
    "status": {
      "description": "Lifecycle stages to include, combined as OR. \"Active\" is under implementation, \"Pipeline\" is approved but not yet effective, \"Closed\" has finished disbursing, and \"Dropped\" was abandoned before approval. Most of the portfolio is closed, so omitting this returns mostly historical operations.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Active",
          "Closed",
          "Dropped",
          "Pipeline"
        ]
      }
    },
    "region": {
      "description": "World Bank operational regions to include, combined as OR. These are the lending regions the portfolio is organized by, not the WDI aggregate codes worldbank_get_data accepts.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "East Asia and Pacific",
          "Europe and Central Asia",
          "Latin America and Caribbean",
          "Middle East, North Africa, Afghanistan, and Pakistan",
          "South Asia",
          "Eastern and Southern Africa",
          "Western and Central Africa",
          "Africa",
          "Other"
        ]
      }
    },
    "approved_from": {
      "description": "Earliest board approval date, as YYYY-MM-DD and inclusive. It must be a real calendar day (2024-02-29, not 2023-02-29) and, when approved_to is also set, on or before it. Board approval is the date the Bank committed to the operation; pipeline projects carry a scheduled date in the future.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Earliest board approval date to include."
        }
      ]
    },
    "approved_to": {
      "description": "Latest board approval date, as YYYY-MM-DD and inclusive. It must be a real calendar day.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Latest board approval date to include."
        }
      ]
    },
    "include_abstract": {
      "default": false,
      "description": "Include each project's abstract. Abstracts run long — a median of roughly 1,200 characters, up to 8,000 — so a page carrying them holds at most 8 projects rather than 80, with every abstract returned whole; leave this off while narrowing a search and turn it on once the result set is small enough to read. Projects that publish no abstract report null either way, which appliedFilters.includeAbstract distinguishes.",
      "type": "boolean"
    },
    "page": {
      "default": 1,
      "description": "Pagination page number (1-based).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Results per page (default: server default, max: 1000). One page holds at most 80 projects, or 8 with include_abstract, which keeps a response within about 50 KB; a larger value, the server default included, is reduced to that cap, disclosed in notice, and echoed as appliedFilters.perPage, and totalPages is counted at the reduced size.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "projects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "World Bank project ID, e.g. P513206."
          },
          "name": {
            "type": "string",
            "description": "Project name."
          },
          "status": {
            "type": "string",
            "description": "Lifecycle stage: Active, Closed, Dropped, or Pipeline."
          },
          "countryCodes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Two-character code of the borrowing country — ISO2 for an economy, a World Bank regional code such as 3A for a multi-country operation. Upstream publishes it as a list, though every project in the portfolio carries exactly one."
          },
          "countryName": {
            "type": "string",
            "description": "Borrowing country, as the portfolio names it."
          },
          "regionName": {
            "type": "string",
            "description": "World Bank operational region."
          },
          "boardApprovalDate": {
            "description": "Date the Board approved the operation, as YYYY-MM-DD. A future date belongs to a pipeline project with a scheduled board date.",
            "type": [
              "string",
              "null"
            ]
          },
          "closingDate": {
            "description": "Scheduled or actual closing date, as YYYY-MM-DD. Null on roughly 44% of the portfolio, which publishes none — almost all dropped operations among them.",
            "type": [
              "string",
              "null"
            ]
          },
          "totalCommitment": {
            "description": "Total World Bank commitment in USD. Null on just over half the portfolio, which publishes no amount — dropped and older operations mostly — and that is not the same as a commitment of zero.",
            "type": [
              "number",
              "null"
            ]
          },
          "financialTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Financing windows behind the operation: IBRD, IDA, Grants, or Other. A blended operation lists more than one."
          },
          "majorSectors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Major sectors the operation is classified under, e.g. Health, Education, Transportation. Empty where the portfolio publishes no sector classification."
          },
          "abstract": {
            "description": "Project abstract. Null when include_abstract was not requested and when the project publishes none — appliedFilters.includeAbstract separates the two.",
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "description": "Project page on projects.worldbank.org."
          }
        },
        "required": [
          "id",
          "name",
          "status",
          "countryCodes",
          "countryName",
          "regionName",
          "boardApprovalDate",
          "closingDate",
          "totalCommitment",
          "financialTypes",
          "majorSectors",
          "abstract",
          "url"
        ],
        "additionalProperties": false,
        "description": "One World Bank lending operation."
      },
      "description": "Projects on this page, newest board approval date first — the order the API returns and the order pagination walks."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "query": {
          "description": "Free-text query applied, omitted when none.",
          "type": "string"
        },
        "countries": {
          "description": "Country codes as sent upstream — uppercased and comma-joined here for readability, though the API itself takes them caret-separated. Omitted when no country filter was applied.",
          "type": "string"
        },
        "status": {
          "description": "Statuses applied, omitted when none.",
          "type": "string"
        },
        "region": {
          "description": "Regions applied, omitted when none.",
          "type": "string"
        },
        "approvedFrom": {
          "description": "Earliest board approval date applied, omitted when none.",
          "type": "string"
        },
        "approvedTo": {
          "description": "Latest board approval date applied, omitted when none.",
          "type": "string"
        },
        "includeAbstract": {
          "type": "boolean",
          "description": "Whether abstracts were requested, including the server default of false. A null abstract means \"not requested\" when this is false and \"none published\" when it is true."
        },
        "page": {
          "type": "number",
          "description": "Page number requested."
        },
        "perPage": {
          "type": "number",
          "description": "Results per page actually served — the requested size or server default, reduced to the page cap when larger. totalPages is counted at this size."
        },
        "requestedPerPage": {
          "description": "Page size asked for, requested or server default, present only when it exceeded the page cap and perPage was reduced.",
          "type": "number"
        }
      },
      "required": [
        "includeAbstract",
        "page",
        "perPage"
      ],
      "additionalProperties": false,
      "description": "The effective search sent upstream — confirms country-code normalization and which filters were in force for these results."
    },
    "totalCount": {
      "type": "number",
      "description": "Total projects matching the search, before pagination."
    },
    "currentPage": {
      "type": "number",
      "description": "Page number requested — past totalPages when the request ran off the end."
    },
    "totalPages": {
      "type": "number",
      "description": "Total number of pages."
    },
    "notice": {
      "description": "Context for an empty result set — including whether the country filter matched anything on its own — for a page past the end of the results, or for a page size reduced to the page cap.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_country_code`: A countries entry is not a two-character code — most often an ISO3 code such as BRA, which the Projects API does not key on. `invalid_date`: approved_from or approved_to is shaped YYYY-MM-DD but names no real day — a month outside 01–12, or a day outside its month. `reversed_date_range`: approved_from falls after approved_to, an interval no project can match. `page_out_of_range`: The requested page starts past the 100,000-result offset the Projects API serves. `upstream_unavailable`: The Projects API answered with a non-success status or an HTML error page. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_country_code",
                "invalid_date",
                "reversed_date_range",
                "page_out_of_range",
                "upstream_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "projects",
        "appliedFilters",
        "totalCount",
        "currentPage",
        "totalPages"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}