Economic Calendar API Guide

The Economic Calendar API provides real-time and historical economic event data covering major global economies. Access upcoming releases, actual vs. forecast values, and detailed indicator metadata through a REST API, receive instant updates via WebSockets, and get push notifications through Webhooks.

Base URL: https://ecowing.theinvestinsight.com/api

Events

List Events

Retrieve a paginated list of economic calendar events with optional filters.

GET /api/events

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number (min: 1)
`limit`	number	50	Items per page (min: 1, max: 200)
`from`	string	—	Start date, ISO-8601 (e.g. `2026-02-01T00:00:00Z`)
`to`	string	—	End date, ISO-8601 (e.g. `2026-02-28T23:59:59Z`)
`currencies`	string	—	Comma-separated currency codes (e.g. `USD,EUR,JPY`)
`importance`	string	—	Comma-separated levels (e.g. `medium,high`)
`country`	number	—	Numeric country code (e.g. `392` for Japan)
`locale`	string	—	Locale code for translated content (see Multi-Language Support)

Example Request

GET /api/events?from=2026-02-01T00:00:00Z&to=2026-02-28T23:59:59Z&currencies=USD,EUR&importance=high&limit=10

Response

{
  "data": [
    {
      "id": 286739,
      "eventType": 0,
      "eventName": "Nonfarm Payrolls",
      "importance": "high",
      "currencyCode": "USD",
      "country": 840,
      "countryName": "United States",
      "forecastValue": "180K",
      "previousValue": "256K",
      "oldPreviousValue": null,
      "actualValue": "143K",
      "releaseDate": "2026-02-07T13:30:00.000Z",
      "fullDate": "2026-02-07T13:30:00.000Z",
      "impactDirection": 2,
      "impactValue": "0.0012",
      "impactValueF": ""
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 87,
    "totalPages": 9
  }
}

Get Event

Retrieve a single event by its ID.

GET /api/events/:id

Query Parameters

Parameter	Type	Required	Description
`locale`	string	No	Locale code for translated content

Response — A single Event object.

Get Event Details

Retrieve detailed metadata for an event's indicator — description, data source, sector, chart data, and upcoming release information.

Multiple events can share the same indicator (e.g. "Nonfarm Payrolls" each month is a different event, but the indicator is the same). Requesting details for any of those events returns the same data.

GET /api/events/:id/details

Query Parameters

Parameter	Type	Required	Description
`locale`	string	No	Locale code for translated content

When locale is provided, the description, sector, and source fields are returned in the requested language (falls back to English if no translation is available).

Response

{
  "data": {
    "description": "Nonfarm Payrolls measures the change in the number of people employed...",
    "sector": "Labor Market",
    "source": "U.S. Bureau of Labor Statistics",
    "nextReleaseDate": "2026-03-06T13:30:00.000Z",
    "nextForecast": "170K",
    "nextPrevious": "143K",
    "chartData": [
      { "index": 0, "timestamp": 1706140800000, "value": 256 },
      { "index": 1, "timestamp": 1708819200000, "value": 143 }
    ]
  },
  "stale": false
}

If details haven't been fetched yet, the API triggers a background fetch and waits up to 10 seconds. If the fetch hasn't completed:

{
  "data": null,
  "stale": true,
  "message": "Details are being fetched. Please retry shortly."
}

Get Event History

Retrieve historical releases for an event's indicator. Like details, history is shared across all events with the same indicator.

GET /api/events/:id/history

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number (min: 1)
`limit`	number	50	Items per page (min: 1, max: 200)

Response

{
  "data": [
    {
      "id": 501,
      "releaseDate": "2026-02-07T13:30:00.000Z",
      "period": "Jan 2026",
      "actualValue": "143K",
      "forecastValue": "180K",
      "previousValue": "256K",
      "oldPreviousValue": null,
      "impactDirection": 2,
      "impactValue": "0.0012",
      "impactValueF": ""
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 120,
    "totalPages": 3
  }
}

Multi-Language Support

Pass the locale query parameter to receive translated content. The following endpoints support localization:

Endpoint	Translated Fields
`GET /api/events`	`eventName`, `countryName`
`GET /api/events/:id`	`eventName`, `countryName`
`GET /api/events/:id/details`	`description`, `sector`, `source`

Supported Locales

Code	Language
`en`	English (default)
`ar`	Arabic
`de`	German
`es`	Spanish
`ja`	Japanese
`pt`	Portuguese
`ru`	Russian
`tr`	Turkish
`zh`	Chinese

If a translation is not available for the requested locale, the English value is returned as a fallback.

Example

GET /api/events?from=2026-03-01T00:00:00Z&to=2026-03-31T23:59:59Z&locale=es&importance=high

{
  "data": [
    {
      "id": 286739,
      "eventType": 0,
      "eventName": "Discurso de la Presidenta del BCE Lagarde",
      "importance": "high",
      "currencyCode": "EUR",
      "country": 999,
      "countryName": null,
      "releaseDate": "2026-03-15T09:30:00.000Z"
    }
  ]
}

Webhooks

Receive push notifications when economic events are created or updated. Configure a subscription with a delivery URL, choose which event types to listen for, and optionally filter by currency or importance level.

Create Subscription

POST /api/webhooks

Request Body

{
  "url": "https://example.com/webhooks/calendar",
  "eventTypes": ["event.actual_released", "event.forecast_updated"],
  "filters": {
    "currencies": ["USD", "EUR"],
    "importance": ["high"]
  }
}

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint to receive deliveries
`eventTypes`	string[]	Yes	At least one event type to subscribe to
`filters`	object	No	Narrow deliveries by currency and/or importance

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/webhooks/calendar",
  "secret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "eventTypes": ["event.actual_released", "event.forecast_updated"],
  "filters": {
    "currencies": ["USD", "EUR"],
    "importance": ["high"]
  },
  "active": true
}

Save the secret — it is only shown in full on creation. Use it to verify delivery signatures.

List Subscriptions

GET /api/webhooks

Returns all subscriptions. Secrets are masked (first 8 + last 4 characters).

Get Subscription

GET /api/webhooks/:id

Update Subscription

PATCH /api/webhooks/:id

Request Body — All fields are optional.

{
  "url": "https://example.com/webhooks/updated",
  "eventTypes": ["event.created"],
  "filters": {
    "currencies": ["JPY"]
  },
  "active": false
}

Set active to false to pause deliveries without deleting the subscription.

Delete Subscription

DELETE /api/webhooks/:id

Response

{
  "deleted": true
}

Get Delivery Log

Inspect the delivery history for a subscription.

GET /api/webhooks/:id/deliveries?page=1&limit=20

Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "eventType": "event.actual_released",
      "payload": { "event": { "id": 286739, "..." : "..." } },
      "status": "delivered",
      "attempts": 1,
      "lastAttemptAt": "2026-02-07T13:31:05.000Z",
      "responseStatus": 200,
      "responseBody": "{\"received\":true}"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}

Delivery Statuses: pending, delivered, failed

Event Types

Event Type	Trigger
`event.created`	A new economic event appears on the calendar
`event.actual_released`	The actual value for an event is published
`event.forecast_updated`	The forecast/consensus value changes
`event.previous_revised`	The previous period's value is revised
`event.details_updated`	Indicator metadata (description, source, etc.) is refreshed

Delivery Format

Each delivery is an HTTP POST to your subscription URL with the following headers:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Event`	Event type (e.g. `event.actual_released`)
`X-Webhook-Delivery-Id`	Unique delivery ID for idempotency
`X-Webhook-Signature`	HMAC-SHA256 hex digest for payload verification

Payload Example (event.actual_released)

{
  "event": {
    "id": 286739,
    "eventName": "Nonfarm Payrolls",
    "currencyCode": "USD",
    "importance": "high",
    "actualValue": "143K",
    "forecastValue": "180K",
    "previousValue": "256K",
    "releaseDate": "2026-02-07T13:30:00.000Z",
    "country": 840,
    "countryName": "United States"
  },
  "previousActual": null,
  "newActual": "143K"
}

Retry Policy: Failed deliveries are retried up to 3 times with exponential backoff (10s, 20s, 40s). Each attempt has a 10-second timeout.

Verifying Signatures

Every delivery includes an X-Webhook-Signature header. Verify it to ensure the request came from the Economic Calendar API and wasn't tampered with.

The signature is computed as:

HMAC-SHA256(raw_request_body, your_subscription_secret)

Node.js Example

import crypto from 'crypto';

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Python Example

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

WebSocket (Real-Time)

Receive real-time updates over a persistent connection using Socket.IO.

Connecting

The WebSocket gateway runs on the same host as the REST API under the /events namespace.

import { io } from 'socket.io-client';

const socket = io('https://ecowing.theinvestinsight.com/events', {
  transports: ['websocket'],
});

socket.on('connect', () => {
  console.log('Connected:', socket.id);
});

All clients automatically join the general events room on connection and receive all broadcasts.

Subscribing to Rooms

Send a subscribe message to receive updates filtered to specific currencies or event IDs.

socket.emit('subscribe', {
  currencies: ['USD', 'EUR'],
  eventIds: [286739],
}, (ack) => {
  console.log(ack);
  // { status: 'ok', rooms: ['events', 'events:USD', 'events:EUR', 'events:286739'] }
});

Field	Type	Description
`currencies`	string[]	Subscribe to currency-specific rooms
`eventIds`	number[]	Subscribe to individual event rooms

Rooms:

Room Pattern	Example	Receives
`events`	`events`	All events (joined automatically)
`events:{CURRENCY}`	`events:USD`	Events for that currency only
`events:{ID}`	`events:286739`	Updates for a specific event only

Unsubscribing

socket.emit('unsubscribe', {
  currencies: ['EUR'],
  eventIds: [286739],
}, (ack) => {
  console.log(ack); // { status: 'ok' }
});

Receiving Events

All updates arrive on the event message:

socket.on('event', (message) => {
  console.log(message.type);      // 'event.actual_released'
  console.log(message.timestamp);  // '2026-02-07T13:31:00.000Z'
  console.log(message.data);       // { eventId, eventName, currencyCode, actualValue, ... }
});

Message Shape

{
  "type": "event.actual_released",
  "timestamp": "2026-02-07T13:31:00.000Z",
  "data": {
    "eventId": 286739,
    "eventName": "Nonfarm Payrolls",
    "currencyCode": "USD",
    "actualValue": "143K",
    "previousActual": null
  }
}

The type field matches the same event types used by webhooks.

Data Reference

Event Object

Field	Type	Description
`id`	number	Unique event ID
`eventType`	number	`0` = speech/report, `1` = numeric indicator, `2` = holiday
`eventName`	string	Human-readable event name (translatable)
`importance`	string	`low`, `medium`, `high`, or `none` (holidays)
`currencyCode`	string	ISO currency code (e.g. `USD`, `EUR`)
`country`	number	Numeric country code
`countryName`	string	null
`forecastValue`	string	null
`previousValue`	string	null
`oldPreviousValue`	string	null
`actualValue`	string	null
`releaseDate`	string	Scheduled release time (ISO-8601, UTC)
`fullDate`	string	Full date/time (ISO-8601, UTC)
`impactDirection`	number	`0` = neutral, `1` = positive, `2` = negative
`impactValue`	string	null
`impactValueF`	string	null

Detail Object

Field	Type	Description
`description`	string	null
`sector`	string	null
`source`	string	null
`nextReleaseDate`	string	null
`nextForecast`	string	null
`nextPrevious`	string	null
`chartData`	array	null

History Row Object

Field	Type	Description
`id`	number	Row ID
`releaseDate`	string	Release date (ISO-8601, UTC)
`period`	string	Reporting period (e.g. "Jan 2026")
`actualValue`	string	null
`forecastValue`	string	null
`previousValue`	string	null
`oldPreviousValue`	string	null
`impactDirection`	number	0 = neutral, 1 = positive, 2 = negative
`impactValue`	string	null
`impactValueF`	string	null

Pagination

All list endpoints return paginated results:

{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1200,
    "totalPages": 24
  }
}

Importance Levels

Value	Description
`none`	Holidays and market closures
`low`	Minor impact — typically market commentary
`medium`	Moderate impact — secondary economic indicators
`high`	Major impact — key releases (NFP, CPI, GDP, rate decisions)

Currency Codes

Common values: USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD, CNY

The currencies filter accepts any code returned by the API. Use GET /api/events without a currency filter to discover all available codes.

Events​

List Events​

Get Event​

Get Event Details​

Get Event History​

Multi-Language Support​

Webhooks​

Create Subscription​

List Subscriptions​

Get Subscription​

Update Subscription​

Delete Subscription​

Get Delivery Log​

Event Types​

Delivery Format​

Verifying Signatures​

WebSocket (Real-Time)​

Connecting​

Subscribing to Rooms​

Unsubscribing​

Receiving Events​

Data Reference​

Event Object​

Detail Object​

History Row Object​

Pagination​

Importance Levels​

Currency Codes​

Events

List Events

Get Event

Get Event Details

Get Event History

Multi-Language Support

Webhooks

Create Subscription

List Subscriptions

Get Subscription

Update Subscription

Delete Subscription

Get Delivery Log

Event Types

Delivery Format

Verifying Signatures

WebSocket (Real-Time)

Connecting

Subscribing to Rooms

Unsubscribing

Receiving Events

Data Reference

Event Object

Detail Object

History Row Object

Pagination

Importance Levels

Currency Codes