> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macrovisonomics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer API & Integrations

> Access MACROVISONOMICS programmatically via REST API, MCP Server for AI agents, OpenAPI specification, and Replit Agent integration

# 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

<CardGroup cols={3}>
  <Card title="REST API" icon="code">
    Standard HTTP endpoints with JSON responses. Works with any programming language.
  </Card>

  <Card title="MCP Server" icon="robot">
    Model Context Protocol server for AI agent compatibility (Claude, GPT, etc.)
  </Card>

  <Card title="OpenAPI Spec" icon="plug">
    Auto-generated Swagger documentation with interactive API explorer.
  </Card>
</CardGroup>

## 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:

```bash theme={null}
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

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

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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

<Steps>
  <Step title="Sign In">
    Log in to your MACROVISONOMICS account at [macrovisonomics.com](https://macrovisonomics.com)
  </Step>

  <Step title="Go to Developer Portal">
    Navigate to the [Developer Portal](https://macrovisonomics.com/developers)
  </Step>

  <Step title="Create a Key">
    Click "Create API Key", give it a name, and select your plan tier
  </Step>

  <Step title="Copy Your Key">
    Copy the generated key immediately -- it will only be shown once
  </Step>
</Steps>

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

### 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](https://modelcontextprotocol.io/) 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:

```json theme={null}
{
  "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:

```bash theme={null}
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

```python theme={null}
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

```javascript theme={null}
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

```bash theme={null}
# 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](https://macrovisonomics.com/developers):

* **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

<AccordionGroup>
  <Accordion title="How do I get an API key?">
    Sign in to MACROVISONOMICS and visit the [Developer Portal](https://macrovisonomics.com/developers). Click "Create API Key" on the API Keys tab.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="What data formats are returned?">
    All API responses are in JSON format. Time-series data includes country codes, year, and value fields.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Developer Portal" icon="code" href="https://macrovisonomics.com/developers">
    Create API keys and view usage
  </Card>

  <Card title="API Docs (Swagger)" icon="book" href="https://macrovisonomics.com/api-docs">
    Interactive API explorer
  </Card>
</CardGroup>