wbgapi360 0.2.1

Enterprise-grade Async Python Client for World Bank Data360 API

wbgapi360: World Bank Data Client for Humans & AI

wbgapi360 is a high-performance Python client designed to interact with the World Bank's Data APIs. It bridges the gap between traditional econometric analysis and modern Artificial Intelligence workflows.

This library is engineered with a Hybrid Architecture: it provides a synchronous, blocking API for human analysts (similar to pandas or matplotlib) and an asynchronous Model Context Protocol (MCP) server for AI Agents (such as Claude or OpenAI).

---

Project Philosophy & Attribution

Unofficial Client

This software is an independent open-source project. It is not affiliated, associated, authorized, endorsed by, or in any way officially connected with The World Bank Group. The official World Bank website can be found at worldbank.org.

Inspiration & Legacy

This project is built upon the conceptual foundation laid by Tim Herzog (tgherzog) and his pioneering work with the original wbgapi.

While wbgapi set the standard for Pythonic access to World Bank data, wbgapi360 was built from the ground up to address two new challenges in the modern era:

1. AI Integration: Native support for LLM function calling via MCP.
2. Smart Search: Heuristic ranking algorithms to disambiguate indicators (e.g., distinguishing "GDP" from "Education Expenditure as % of GDP").

We acknowledge and thank Tim for establishing the developer-friendly patterns that inspired this library's human interface.

---

Installation

The library is available on PyPI.

# Core installation (Lightweight)
pip install wbgapi360

# With Visualization support (adds Matplotlib/Seaborn)
pip install wbgapi360[visual]

# With Mapping support (adds GeoPandas - Heavy dependency)
pip install wbgapi360[map]

---

Usage Guide: For Analysts (Python)

The human interface is designed to be intuitive, synchronous, and safe for Jupyter Notebooks.

1. Smart Search (Semantic)

Finding the right indicator among 16,000+ options is difficult. wbgapi360 uses a heuristic ranking system.

import wbgapi360 as wb

# Search for "inflation" - automatically ranks "Consumer Price Index" above obscure sub-metrics
results = wb.search("inflation") # Returns top 10 matches

for r in results[:3]:
    print(f"[{r['code']}] {r['name']}")
    # Output:
    # [FP.CPI.TOTL.ZG] Inflation, consumer prices (annual %)
    # [FP.CPI.TOTL] Consumer price index (2010 = 100)
    # [NY.GDP.DEFL.KD.ZG] Inflation, GDP deflator (annual %)

2. Robust Data Retrieval

Fetch data with automatic ID correction and intelligent time window handling.

# Fetch GDP Growth for USA, China, and Peru (Last 10 years)
df = wb.get_data(
    indicator="NY.GDP.MKTP.KD.ZG", 
    economies=["USA", "CHN", "PER"],
    years=10,
    labels=True,      # Adds 'Country Name' column
    as_frame=True     # Returns pandas DataFrame instead of JSON
)

print(df.head())

3. Advanced Analysis: Trends & Statistics

Quickly assess the economic trajectory of a country without writing boilerplate pandas code.

# Analyze the trend of Foreign Direct Investment in Chile
stats = wb.analyze_trend(
    indicator="BX.KLT.DINV.CD.WD", 
    economy="CHL", 
    years=20
)

# Returns a rich JSON with growth rates, volatility, and direction
# {
#   "statistics": {
#     "avg_annual_growth_pct": 5.2,
#     "volatility": 1240000000,
#     "trend_direction": "increasing"
#   }
# }

4. Professional Visualization

Generate Financial Times-style charts ready for publication.

# 1. Fetch Data
data = wb.get_data("NY.GDP.PCAP.CD", ["CHL", "PER", "COL", "MEX"], years=15)

# 2. Plot Trend
wb.plot(
    chart_type="trend", 
    data=data, 
    title="Pacific Alliance: GDP per Capita",
    subtitle="Current US$ (2010-2025)",
    save_path="pacific_gdp.png"
)

---

Usage Guide: For AI Agents (MCP)

This library implements the Model Context Protocol (MCP), allowing AI agents (like Claude or Custom GPTs) to autonomously interact with World Bank data using high-level tools.

1. Configuration (Claude Desktop)

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "worldbank": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/mcp_wbgapi360",
        "run",
        "wbgapi360"
      ]
    }
  }
}

2. Available Tools

The Agent receives a toolkit optimized for economic reasoning:

Tool	Description	Signature
search_indicators	Semantic search. Finds the best matching indicator codes.	(query: str) -> List[Indicator]
get_data	Fetches time-series data for analysis.	(indicator_code: str, economies: List[str], years: int)
compare_countries	Comparison logic. Fetches and normalizes data for multiple countries.	(economies: List[str], indicators: List[str])
analyze_trend	Returns statistical descriptive metadata (growth, volatility).	(indicator: str, economy: str)
rank_countries	Returns a sorted leaderboard for a given indicator.	(indicator: str, region: str, top_n: int)
plot_chart	Generates a visualization file from data.	(chart_type: str, data: json)

3. Example Prompts

Once connected, you can ask the Agent complex economic questions:

"Compare the GDP growth volatility between Peru and Chile over the last 20 years. Who has been more stable?"

• Agent Action: Calls analyze_trend for both countries and compares the volatility metric.

"Create a bar chart ranking the top 10 Latin American countries by Inflation."

• Agent Action: Calls rank_countries(indicator="FP.CPI.TOTL.ZG", region="latam") then plot_chart(chart_type="bar", ...).

"Is there a correlation between Literacy Rate and GDP per Capita in Africa?"

• Agent Action: Calls compare_countries with both indicators for African nations, then plot_chart(chart_type="scatter").

---

Visualization Gallery

The library supports specific chart types optimized for economic data:

Type	Description	Use Case
Trend	Multi-line time series	GDP Growth over time
Bar	Horizontal ranked bars	Comparing GINI index across countries
Column	Vertical categorical bars	Exports by region
Scatter	Correlation plot	Life Expectancy vs. GDP per Capita
Map	Choropleth map	Global population density (Requires geopandas)

---

Author

Maykol Medrano
Applied Economist Policy Data Scientist
Email: [e-mail]

---

License

This project is licensed under the MIT License - see the LICENSE file for details.