API Documentation

Everything you need to use Hindsight Data API.

Authentication

All API requests (except /getSample) require authentication using your API key. You can pass your API key in any one of three ways:

1. X-API-Key Header (Recommended)

X-API-Key: hindsight_live_xxxxx

2. Authorization Header (Bearer Token)

Authorization: Bearer hindsight_live_xxxxx

3. Query Parameter

?api_key=hindsight_live_xxxxx

You receive your API key after purchase. You can rotate your key at any time via the API.

Base URL

All API requests should be made to:

https://hindsightapi.com/api

Endpoints

GET/getData

Retrieve economic calendar data for a date range. Requires authentication.

Query Parameters

Parameter	Type	Description
`start_date`	string	Start date (YYYY-MM-DD)
`end_date`	string	End date (YYYY-MM-DD)
`country`	string	Filter by country code (US, UK, EU, etc.)
`min_volatility`	integer	Minimum volatility level (1-3, where 3 is highest impact)
`event`	string	Filter by event name (e.g. "CFTC", "PPI", "FOMC")
`format`	string	Response format: "json" (default) or "csv"

Example Requests

JSON format (default):

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-08-05&end_date=2024-08-05&country=US&event=PMI" \
  -H "X-API-Key: hindsight_live_xxxxx"

CSV format:

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-08-05&end_date=2024-08-05&format=csv" \
  -H "X-API-Key: hindsight_live_xxxxx"

GET/getSample

Get free sample data (August-September 2023, US markets, volatility 2+). No authentication required.

Example Request

curl "https://hindsightapi.com/api/getSample"

Response Format

Responses can be in JSON or CSV format based on the format query parameter.

JSON Format (Default)

[
  {
    "actual": "3.3%",
    "country": "US",
    "date": "2025-01-13",
    "event_name": "PPI (YoY) (Dec)",
    "forecast": "3.5%",
    "previous": "3.0%",
    "time": "08:30",
    "timezone": "America/New_York",
    "volatility": 2
  },
  {
    "actual": "0.1%",
    "country": "US",
    "date": "2025-01-13",
    "event_name": "PPI ex. Food/Energy/Transport (MoM) (Dec)",
    "forecast": "0.3%",
    "previous": "0.1%",
    "time": "08:30",
    "timezone": "America/New_York",
    "volatility": 2
  }
]

CSV Format

Add format=csv to download data as CSV.

date,time,event_name,actual,forecast,previous,volatility,timezone,country
2025-01-13,06:00,NFIB Small Business Optimism  (Dec),105.1,101.3,101.7,2,America/New_York,US
2025-01-13,08:30,PPI (YoY) (Dec),3.3%,3.5%,3.0%,2,America/New_York,US
2025-01-13,08:30,PPI ex. Food/Energy/Transport (MoM) (Dec),0.1%,0.3%,0.1%,2,America/New_York,US

Field Descriptions

Field	Description
`date`	Event date (YYYY-MM-DD)
`time`	Event time (HH:MM)
`timezone`	Timezone for the event time
`country`	Country code (e.g., US, UK, EU)
`event_name`	Name of the economic event
`volatility`	Impact level (1=low, 2=medium, 3=high)
`actual`	Actual reported value (null if not yet released)
`forecast`	Consensus forecast value
`previous`	Previous period value

Examples

Here are some practical examples to help you get started with common use cases.

Get All Past FOMC Meeting Dates

Use the event parameter to filter for Federal Open Market Committee events.

curl -X GET "https://hindsightapi.com/api/getData?start_date=2023-01-01&end_date=2023-12-31&event=FOMC&country=US" \
  -H "X-API-Key: hindsight_live_xxxxx"

This returns all events containing "FOMC" in the event name for 2023.

Get Producer Price Index (PPI) Data

Filter for all PPI-related events in a specific date range.

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-01-01&end_date=2024-06-30&event=PPI&country=US" \
  -H "X-API-Key: hindsight_live_xxxxx"

This returns PPI, Core PPI, and all other PPI-related events.

High Volatility Employment Data as CSV

Combine multiple filters and get results in CSV format.

curl -X GET "https://hindsightapi.com/api/getData?start_date=2024-01-01&end_date=2024-12-31&event=Employment&min_volatility=3&format=csv" \
  -H "X-API-Key: hindsight_live_xxxxx" \
  -o employment-data-2024.csv

This downloads high-impact employment events as a CSV file.

Error Handling

The API uses standard HTTP status codes:

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing API key
`403`	Forbidden - Invalid or expired API key
`500`	Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Invalid API key"
}

{
    "success": false,
    "error": "Requested end_date exceeds your subscription limit",
    "subscriptionEnd": "2022-03-11"
}

Need Help?

If you have any questions or need assistance, reach out to us at hi@fullstackcraft.com