Calendar API Reference

The Calendar API provides a public social media event calendar for 2026, covering public holidays, awareness days, cultural events, commerce dates, and sensitive/no-post dates across the world’s 20 largest economies.

Endpoints

Method	Endpoint	Description
`GET`	`/api/calendar`	List calendar events

List calendar events

GET /api/calendar

Retrieves a filtered, paginated list of calendar events for 2026.

Query parameters

Parameter	Type	Required	Default	Description
`category`	string	No	-	Filter by category. Comma-separated. Values: `post_trigger`, `sensitive`, `no_post`
`type`	string	No	-	Filter by event type. Comma-separated. Values: `public_holiday`, `fun_holiday`, `awareness_day`, `cultural_event`, `sporting_event`, `commerce_event`, `religious_event`, `seasonal`, `remembrance`
`country`	string	No	-	Filter by country code (ISO 3166-1 alpha-2). Comma-separated. Also includes global events
`tag`	string	No	-	Filter by tag. Comma-separated. Examples: `sports`, `food`, `pets`, `commerce`, `environment`
`month`	integer	No	-	Filter by month (1–12)
`q`	string	No	-	Search event names (case-insensitive)
`from`	string	No	-	Start of date range (YYYY-MM-DD)
`to`	string	No	-	End of date range (YYYY-MM-DD)
`page`	integer	No	`0`	Page number (zero-indexed)
`per_page`	integer	No	`50`	Results per page (1–100)

Examples

Get all events:

curl -X GET "https://api.postproxy.com/api/calendar"

Get no-post / sensitive dates:

curl -X GET "https://api.postproxy.com/api/calendar?category=no_post,sensitive"

Get Black Friday week events for US:

curl -X GET "https://api.postproxy.com/api/calendar?country=US&from=2026-11-25&to=2026-12-01"

Get all sporting events:

curl -X GET "https://api.postproxy.com/api/calendar?type=sporting_event"

Search by name:

curl -X GET "https://api.postproxy.com/api/calendar?q=coffee"

Combine filters — fun holidays in December with food tag:

curl -X GET "https://api.postproxy.com/api/calendar?type=fun_holiday&month=12&tag=food"

Response

{
  "total": 284,
  "page": 0,
  "per_page": 50,
  "filters": {},
  "data": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "type": "public_holiday",
      "category": "post_trigger",
      "countries": ["US", "CN", "DE", "JP", "FR", "IT", "CA", "BR", "RU", "KR", "AU", "MX", "ES", "ID", "NL", "TR", "CH"],
      "tags": []
    }
  ]
}

Response fields

Field	Type	Description
`total`	integer	Total number of events matching the filters
`page`	integer	Current page number
`per_page`	integer	Number of results per page
`filters`	object	Echo of active filters applied to the request
`data`	array	Array of event objects

Event object

Field	Type	Description
`date`	string	Event date (YYYY-MM-DD)
`name`	string	Event name
`type`	string	Event type (see values below)
`category`	string	One of `post_trigger`, `sensitive`, `no_post`
`countries`	array\|null	Country codes where applicable, or null for global events
`tags`	array	Descriptive tags for filtering
`posting_tip`	string\|null	Optional social media posting guidance

Event types

Type	Description
`public_holiday`	Official government holidays
`fun_holiday`	Quirky/informal holidays (National Pizza Day, etc.)
`awareness_day`	Awareness and advocacy days (World Mental Health Day, etc.)
`cultural_event`	Cultural celebrations and awards (Oscars, Halloween, etc.)
`sporting_event`	Major sporting events (Super Bowl, FIFA World Cup, etc.)
`commerce_event`	Shopping/commerce events (Black Friday, Cyber Monday, etc.)
`religious_event`	Religious observances (Ramadan, Diwali, etc.)
`seasonal`	Seasonal markers (solstices, equinoxes, etc.)
`remembrance`	Memorial and remembrance dates

Category	Description
`post_trigger`	Good opportunity to post — plan content around these dates
`sensitive`	Post with care — be respectful, avoid commercial tie-ins
`no_post`	Brands should stay silent or share only respectful acknowledgment

Available countries

The calendar covers public holidays for 17 countries (top 20 economies; India and Saudi Arabia are not yet available):

US, CN, DE, JP, GB, FR, IT, CA, BR, RU, KR, AU, MX, ES, ID, NL, TR, CH