--- title: Macroeconomic Release Calendar API created: 2026-09-29 updated: 2026-09-29 endpoint: POST v1/market/calendars auth: Bearer Token --- # Macroeconomic Release Calendar API Returns scheduled macroeconomic events, indicators, and data releases for countries globally (e.g., Unemployment Rate, CPI, Retail Sales). **Available via:** [REST API](https://developers.finimpulse.com/) · [MCP](https://developers.finimpulse.com/model-context-protocol/) This endpoint provides scheduled macroeconomic data releases for 71 countries and the euro area, covering recent releases and upcoming events for approximately the next 30 days. Each record covers one indicator release for one country and contains the release date and time, the reference period, and the actual, prior, and originally reported values. ## Coverage **Countries**Global coverage across supported countries and markets.**Events**Scheduled macroeconomic releases, including indicators such as unemployment, CPI, retail sales, GDP, interest rates, and other country-level economic data.**Future** **Availability**Upcoming events are generally available for approximately the next 30 days. The maximum future date currently available may vary by source and indicator.## Data Freshness Data is updated weekly. Newly published values may appear in **after_release_actual** with a delay of up to one week after the release. ## Data Availability & Limitations - The endpoint provides scheduled macroeconomic releases by country and indicator. - Upcoming events are generally available for approximately the next 30 days. - Future events may have **null** values for **after_release_actual** until the data is published. - After an event occurs, its record remains available through the endpoint. The **after_release_actual** value may continue to be populated or updated for approximately one month after the event. - Event availability varies by country, indicator, and source. - Release dates and times may change when updated by the source. - Macroeconomic event data is refreshed weekly. ## When to Use This Endpoint - Build comprehensive global economic event calendars. - Track the exact release dates and times for crucial macroeconomic indicators. - Compare newly released economic data against prior or originally reported numbers to analyze market impact. - Filter upcoming events by specific dates or countries. ## Request Parameters **POST** `v1/market/calendars` - **filters** `array` *(optional)* — Optional filter expressions. Each filter condition is defined as: `[field, operator, value]`. Conditions can be combined using logical operators `and`/`or`. **Supported operators:** *Numeric fields:* - `>` - greater than - `>=` - greater than or equal - `<` - less than - `<=` - less than or equal - `=` - equals - `<>` - not equal *String fields:* - `like` – pattern match (requires `%` as a wildcard) - `not_like` - pattern does not match (requires `%` as a wildcard) - `contains` - value exists in string - `not_contains` - value does not exist in string - `startswith` - string starts with value - `endswith` - string ends with value `%` *usage examples:* - `%abc%` - matches any string containing "abc" - `abc%` - matches any string starting with "abc" - `%abc` - matches any string ending with "abc" - **sort_by** `array` *(optional)* — Optional sorting configuration for result items. Each sorting setup is defined as an object `{selector, desc}`: - `selector` - Field used for sorting (e.g., start_date_time). - `desc` - Sorting direction (*true* for descending, *false* for ascending). Multiple sorting setups can be combined in the array. By default, results are sorted by `start_date_time` in descending order, then by `economic_release` in alphabetical order. - **limit** `integer` *(optional)* — Maximum number of matched items returned (user-defined). - Default: 100 - Maximum: 1000 - **offset** `integer` *(optional)* — Pagination offset (0-based) - **tag** `string` *(optional)* — User-defined identifier for the task (max 255 characters). It is returned in the response data object, allowing you to match results with the corresponding request. It does not affect API processing or filtering logic. ### Example Request ```bash curl --location "https://api.finimpulse.com/v1/market/calendars" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer " \ -d '{ "filters": [ [ "country_code_iso3", "=", "JPN" ], "and", [ "start_date_time", ">=", "2026-09-28" ] ], "sort_by": [ { "selector": "start_date_time", "desc": false }, { "selector": "economic_release", "desc": false } ], "limit": 10, "offset": 0 }' ``` ```clike using System.Net.Http; using System.Net.Http.Headers; using System.Text; var client = new HttpClient(); var url = "https://api.finimpulse.com/v1/market/calendars"; client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", ""); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); var json = @"{ ""filters"": [ [ ""country_code_iso3"", ""="", ""JPN"" ], ""and"", [ ""start_date_time"", "">="", ""2026-09-28"" ] ], ""sort_by"": [ { ""selector"": ""start_date_time"", ""desc"": false }, { ""selector"": ""economic_release"", ""desc"": false } ], ""limit"": 10, ""offset"": 0 }"; var content = new StringContent(json, Encoding.UTF8, "application/json"); var response = await client.PostAsync(url, content); var result = await response.Content.ReadAsStringAsync(); Console.WriteLine(result); ``` ```php "https://api.finimpulse.com/v1/market/calendars", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "Authorization: Bearer " ], CURLOPT_POSTFIELDS => json_encode( [ "filters" => [ [ "country_code_iso3", "=", "JPN" ], "and", [ "start_date_time", ">=", "2026-09-28" ] ], "sort_by" => [ [ "selector" => "start_date_time", "desc" => false ], [ "selector" => "economic_release", "desc" => false ] ], "limit" => 10, "offset" => 0 ] ) ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```python import urllib.request import json url = "https://api.finimpulse.com/v1/market/calendars" headers = { "Content-Type": "application/json", "Authorization": "Bearer " } data = { "filters": [ [ "country_code_iso3", "=", "JPN" ], "and", [ "start_date_time", ">=", "2026-09-28" ] ], "sort_by": [ { "selector": "start_date_time", "desc": False }, { "selector": "economic_release", "desc": False } ], "limit": 10, "offset": 0 } req = urllib.request.Request(url, data=json.dumps(data).encode("utf-8"), headers=headers, method="POST") with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode("utf-8")) print(result) ``` ```javascript const https = require('https'); const data = JSON.stringify({ "filters": [ [ "country_code_iso3", "=", "JPN" ], "and", [ "start_date_time", ">=", "2026-09-28" ] ], "sort_by": [ { "selector": "start_date_time", "desc": false }, { "selector": "economic_release", "desc": false } ], "limit": 10, "offset": 0 }); const options = { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ', 'Content-Length': Buffer.byteLength(data) } }; const req = https.request('https://api.finimpulse.com/v1/market/calendars', options, (res) => { let body = ''; res.on('data', chunk => body += chunk); res.on('end', () => console.log(JSON.stringify(JSON.parse(body), null, 2))); }); req.on('error', (e) => console.error(e)); req.write(data); req.end(); ``` ## Response ### Pagination Fields - **total_count** `integer` — Total number of matching records. - **items_count** `integer` — Number of records returned. - **items** `array` — Array of economic event records. ### Event Details - **economic_release** `string` — The name of the economic metric or event being reported (e.g., "All Household Spending MM", "Unemployment Rate"). - **country_code_iso3** `string` — The 3-letter ISO 3166-1 alpha-3 code of the country releasing the data (e.g., "JPN" for Japan, "USA" for the United States). - **start_date_time** `string` — The scheduled UTC date and time of the data release in ISO 8601 format (e.g., "2026-08-06T23:30:00Z"). - **period** `string` — The specific reference period the released data applies to (e.g., "Jun", "Q2"). ### Release Metrics - **after_release_actual** `number` — The actual value reported for the current release. May be null for future events until the value is published. - **prior_release_actual** `number` — The value reported for the previous release period. - **originally_reported_actual** `number` — The previously reported value before subsequent revisions. ### Example Response ```json { "result": { "total_count": 30, "items_count": 1, "items": [ { "economic_release": "All Household Spending MM", "country_code_iso3": "JPN", "start_date_time": "2026-08-06T23:30:00Z", "period": "Jun", "after_release_actual": -6.4, "prior_release_actual": 3.7, "originally_reported_actual": null } ] } } ``` ## Units & Values The API does not provide a separate unit or scale field for calendar events. Values in **after_release_actual**, **prior_release_actual**, and **originally_reported_actual** may represent percentages, index points, currency amounts, or other units depending on the economic release. The scale of currency amounts (for example, millions or billions) is also not specified and may differ between releases. Use **economic_release** to identify the indicator being reported and interpret the value according to that indicator's standard unit. ## Pagination & Limits You can control how many records a response returns and page through large result sets using the **limit** and **offset** parameters. - Use **limit** to set the number of records per request, from 1 to 1000. If **limit** is not specified, up to 100 records are returned. - Use **offset** to skip records (0-based). For example, **limit**: 100 and **offset**: **100** return records 101–200. - To retrieve all matching records, increase **offset** by the **limit** value until **offset** + **items_count** reaches **total_count**. - To keep the order consistent across pages, pass **sort_by**, for example, by **start_date_time**, **economic_release**, and **country_code_iso3**. Each returned record is billed as a Row, so the cost of a request depends on the number of records returned. ## API Pricing - Call: **$0.00030** - Row: **$0.00005** ## Related APIs - [Country Macroeconomic Indicators API](https://developers.finimpulse.com/v1/macro-economics/) - [Corporate Earnings & IPO Calendar API](https://developers.finimpulse.com/v1/events/tickers/) ## Related Resources - [API Sandbox](https://developers.finimpulse.com/sandbox/) - [MCP Server](https://developers.finimpulse.com/model-context-protocol/) - [Glossary](https://finimpulse.com/glossary/) - [API Pricing](https://finimpulse.com/api/pricing/)