Developer API & Integrations

MACROVISONOMICS provides a full Developer Platform for programmatic access to economic data. Whether you’re building dashboards, integrating with AI agents, or automating research workflows, the platform offers multiple integration methods to fit your needs.

Integration Methods

REST API

Standard HTTP endpoints with JSON responses. Works with any programming language.

MCP Server

Model Context Protocol server for AI agent compatibility (Claude, GPT, etc.)

OpenAPI Spec

Auto-generated Swagger documentation with interactive API explorer.

REST API

Base URL

All API endpoints are prefixed with /api/v1/:

https://macrovisonomics.com/api/v1/

Authentication

All API requests require an API key passed via the X-API-Key header:

curl -X GET "https://macrovisonomics.com/api/v1/search?q=GDP+growth" \
  -H "X-API-Key: your_api_key" \
  -H "Accept: application/json"

Available Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/search?q=...`	Semantic indicator search
`GET`	`/api/v1/indicators/:id`	Indicator metadata
`GET`	`/api/v1/indicators/:id/data`	Time-series data with country/year filters
`GET`	`/api/v1/countries`	List all 217+ countries
`GET`	`/api/v1/countries/:code`	Country detail and key indicators
`GET`	`/api/v1/insights`	AI-generated insights for indicator + countries
`GET`	`/api/v1/forecast`	Trend-based forecasting with linear regression

Example: Search for Indicators

curl "https://macrovisonomics.com/api/v1/search?q=unemployment+rate" \
  -H "X-API-Key: mv_live_abc123"

Response:

{
  "data": [
    {
      "id": "SL.UEM.TOTL.ZS",
      "name": "Unemployment, total (% of total labor force)",
      "source": "World Bank",
      "category": "Labor & Employment"
    }
  ],
  "meta": {
    "rateLimit": { "limit": 60, "remaining": 59, "reset": 1700000060 }
  }
}

Example: Fetch Time-Series Data

curl "https://macrovisonomics.com/api/v1/indicators/NY.GDP.MKTP.CD/data?countries=USA,CAN&start_year=2015&end_year=2023" \
  -H "X-API-Key: mv_live_abc123"

Rate Limiting

Every API response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`X-RateLimit-Window`	Duration of the rate limit window

Rate limits vary by plan:

Plan	Rate Limit
Pro	60 requests/minute
Gold	200 requests/minute
Enterprise	Custom (up to 2,000 requests/minute)

API access requires Pro or above. Free accounts cannot create API keys. When you exceed your rate limit, you’ll receive a 429 Too Many Requests response.

Error Handling

The API returns standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request (invalid parameters)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (insufficient permissions)
`429`	Rate limit exceeded
`500`	Server error

API Key Management

Getting Your API Key

Go to Developer Portal

Navigate to the Developer Portal

Create a Key

Click “Create API Key”, give it a name, and select your plan tier

Copy Your Key

Copy the generated key immediately — it will only be shown once

API keys are shown only once when created. Store your key securely. If you lose it, you’ll need to create a new one.

Key Security Best Practices

Never expose your API key in client-side code or public repositories
Use environment variables to store keys in your applications
Rotate keys periodically for enhanced security
Create separate keys for different applications or environments
Revoke unused keys from the Developer Portal

MCP Server (AI Agent Integration)

The MACROVISONOMICS MCP Server implements the Model Context Protocol for seamless integration with AI assistants like Claude, ChatGPT, and other LLM-based tools.

Available Tools

The MCP server exposes 7 tools:

Tool	Description
`search_indicators`	Semantic search for economic indicators
`get_indicator_data`	Fetch time-series data for an indicator
`get_indicator_metadata`	Get detailed metadata for an indicator
`list_countries`	List all available countries
`get_country_detail`	Get an economic overview of a country
`get_ai_insights`	Generate AI-powered insights
`get_forecast`	Generate trend-based forecasts

Connecting to the MCP Server

Add the following to your MCP client configuration:

{
  "mcpServers": {
    "macrovisonomics": {
      "command": "node",
      "args": ["path/to/mcp-server.js"],
      "env": {
        "MACROVISONOMICS_API_KEY": "your_api_key"
      }
    }
  }
}

Example: Using with Claude

Once connected, you can ask Claude questions like:

“Search for GDP growth indicators”
“Get unemployment data for G7 countries from 2015 to 2023”
“Generate insights on inflation trends in BRICS nations”

The MCP server handles the API calls and returns structured data to the AI assistant.

OpenAPI Specification

Interactive Documentation

Browse the full API documentation with an interactive explorer at:

https://macrovisonomics.com/api-docs

The Swagger UI allows you to:

View all available endpoints and their parameters
Try API calls directly from the browser
See request/response schemas and examples
Download the OpenAPI spec for code generation

Generating Client Libraries

Download the OpenAPI specification and use tools like openapi-generator to create client libraries in any language:

openapi-generator generate \
  -i https://macrovisonomics.com/api-docs/openapi.yaml \
  -g python \
  -o ./macrovisonomics-client

GPT Actions

The OpenAPI spec is fully compatible with OpenAI GPT Actions. You can create a custom GPT that queries MACROVISONOMICS data by importing the spec into the GPT Builder.

Code Examples

Python

import requests

API_KEY = "mv_live_your_key_here"
BASE_URL = "https://macrovisonomics.com/api/v1"

headers = {"X-API-Key": API_KEY}

# Search for indicators
response = requests.get(
    f"{BASE_URL}/search",
    params={"q": "GDP growth"},
    headers=headers
)
results = response.json()

# Fetch time-series data
response = requests.get(
    f"{BASE_URL}/indicators/NY.GDP.MKTP.KD.ZG/data",
    params={"countries": "USA,CAN,GBR", "start_year": 2010, "end_year": 2023},
    headers=headers
)
data = response.json()

JavaScript / Node.js

const API_KEY = "mv_live_your_key_here";
const BASE_URL = "https://macrovisonomics.com/api/v1";

const headers = { "X-API-Key": API_KEY };

// Search for indicators
const searchRes = await fetch(
  `${BASE_URL}/search?q=unemployment+rate`,
  { headers }
);
const results = await searchRes.json();

// Fetch data
const dataRes = await fetch(
  `${BASE_URL}/indicators/SL.UEM.TOTL.ZS/data?countries=USA,DEU`,
  { headers }
);
const data = await dataRes.json();

cURL

# Search
curl "https://macrovisonomics.com/api/v1/search?q=inflation" \
  -H "X-API-Key: mv_live_your_key_here"

# Get indicator data
curl "https://macrovisonomics.com/api/v1/indicators/FP.CPI.TOTL.ZG/data?countries=USA&start_year=2020" \
  -H "X-API-Key: mv_live_your_key_here"

# List countries
curl "https://macrovisonomics.com/api/v1/countries" \
  -H "X-API-Key: mv_live_your_key_here"

Usage Tracking

Monitor your API usage from the Developer Portal:

Total requests: Track your API call volume over time
Response times: Monitor average and p95 response times
Endpoint breakdown: See which endpoints you use most
Rate limit status: Check how close you are to your limits
Error rates: Identify and troubleshoot failed requests

Frequently Asked Questions

How do I get an API key?

What rate limits apply to my API key?

API access requires Pro or above. Pro gets 60 requests/minute (500 calls/month), Gold gets 200 requests/minute (2,000 calls/month), and Enterprise plans support custom limits with unlimited monthly calls. Free accounts cannot create API keys.

Can I use the API with AI agents like Claude or ChatGPT?

Yes. Use the MCP Server for Claude integration or import the OpenAPI specification into GPT Actions for ChatGPT. Both methods are fully supported.

Is there a sandbox or test environment?

API keys work against production data. To test the API before committing to a paid plan, start a 7-day Pro trial — no credit card required — which gives you 500 API calls to explore all 7 endpoints.

What data formats are returned?

All API responses are in JSON format. Time-series data includes country codes, year, and value fields.

Getting Started

Features

Explore & Markets

Reference Guides

Help & Support

Legal

Developer API & Integrations

Developer API & Integrations

Integration Methods

REST API

MCP Server

OpenAPI Spec

REST API

Base URL

Authentication

Available Endpoints

Example: Search for Indicators

Example: Fetch Time-Series Data

Rate Limiting

Error Handling

API Key Management

Getting Your API Key

Key Security Best Practices

MCP Server (AI Agent Integration)

Available Tools

Connecting to the MCP Server

Example: Using with Claude

OpenAPI Specification

Interactive Documentation

Generating Client Libraries

GPT Actions

Code Examples

Python

JavaScript / Node.js

cURL

Usage Tracking

Frequently Asked Questions

Next Steps

Developer Portal

API Docs (Swagger)

Getting Started

Features

Explore & Markets

Reference Guides

Help & Support

Legal

​Developer API & Integrations

​Integration Methods

REST API

MCP Server

OpenAPI Spec

​REST API

​Base URL

​Authentication

​Available Endpoints

​Example: Search for Indicators

​Example: Fetch Time-Series Data

​Rate Limiting

​Error Handling

​API Key Management

​Getting Your API Key

​Key Security Best Practices

​MCP Server (AI Agent Integration)

​Available Tools

​Connecting to the MCP Server

​Example: Using with Claude

​OpenAPI Specification

​Interactive Documentation

​Generating Client Libraries

​GPT Actions

​Code Examples

​Python

​JavaScript / Node.js

​cURL

​Usage Tracking

​Frequently Asked Questions

​Next Steps

Developer Portal

API Docs (Swagger)

Developer API & Integrations

Integration Methods

REST API

Base URL

Authentication

Available Endpoints

Example: Search for Indicators

Example: Fetch Time-Series Data

Rate Limiting

Error Handling

API Key Management

Getting Your API Key

Key Security Best Practices

MCP Server (AI Agent Integration)

Available Tools

Connecting to the MCP Server

Example: Using with Claude

OpenAPI Specification

Interactive Documentation

Generating Client Libraries

GPT Actions

Code Examples

Python

JavaScript / Node.js

cURL

Usage Tracking

Frequently Asked Questions

Next Steps