Endpoint
POST https://requiems.xyz/v1/places/holidays/batch
Batch Get Holidays
Returns holidays for up to 50 (country, year) pairs in a single request. Each pair is processed independently — if one combination has no data, it returns found:false without failing the entire batch.
Parameters
| Name |
Type |
Required |
Location |
Description |
queries |
array |
yes |
body |
Array of (country, year) pairs. Min: 1, Max: 50. |
Response Example
{
"data": {
"results": [
{
"country": "US",
"year": 2025,
"found": true,
"holidays": [
{ "date": "2025-01-01", "name": "New Year's Day" },
{ "date": "2025-07-04", "name": "Independence Day" }
],
"total": 11
},
{
"country": "AR",
"year": 2024,
"found": true,
"holidays": [
{ "date": "2024-01-01", "name": "Año Nuevo" }
],
"total": 19
},
{
"country": "AQ",
"year": 2025,
"found": false
}
],
"total": 3
},
"metadata": {
"timestamp": "2025-01-15T10:30:00Z"
}
}
Response Fields
| Field |
Type |
Description |
results |
array |
One result per query, in the same order as the request |
results[].country |
string |
ISO 3166-1 alpha-2 country code |
results[].year |
integer |
Year queried |
results[].found |
boolean |
false when no holidays exist for that country/year combination |
results[].holidays |
array |
List of holidays. Omitted when found is false. |
results[].total |
integer |
Number of holidays. Omitted when found is false. |
total |
integer |
Total number of results (equals the number of queries sent) |
Errors
400 bad_request — Malformed request body422 validation_failed — queries is missing, empty, exceeds 50 items, or contains invalid country codes or years
1---
2name: holidays-post-batch
3api: Holidays
4method: POST
5path: /v1/places/holidays/batch
6base_url: https://requiems.xyz
7description: Returns holidays for up to 50 (country, year) pairs in a single request. Each pair is processed independently — if one combination has no data, it returns found:false without failing the entire batch.
8---
9
10## Endpoint
11
12**POST https://requiems.xyz/v1/places/holidays/batch**
13
14## Batch Get Holidays
15
16Returns holidays for up to 50 (country, year) pairs in a single request. Each pair is processed independently — if one combination has no data, it returns found:false without failing the entire batch.
17
18## Parameters
19
20| Name | Type | Required | Location | Description |
21| ---- | ---- | -------- | -------- | ----------- |
22| `queries` | array<object> | yes | body | Array of (country, year) pairs. Min: 1, Max: 50. |
23
24## Response Example
25
26```json
27{
28 "data": {
29 "results": [
30 {
31 "country": "US",
32 "year": 2025,
33 "found": true,
34 "holidays": [
35 { "date": "2025-01-01", "name": "New Year's Day" },
36 { "date": "2025-07-04", "name": "Independence Day" }
37 ],
38 "total": 11
39 },
40 {
41 "country": "AR",
42 "year": 2024,
43 "found": true,
44 "holidays": [
45 { "date": "2024-01-01", "name": "Año Nuevo" }
46 ],
47 "total": 19
48 },
49 {
50 "country": "AQ",
51 "year": 2025,
52 "found": false
53 }
54 ],
55 "total": 3
56 },
57 "metadata": {
58 "timestamp": "2025-01-15T10:30:00Z"
59 }
60}
61```
62
63## Response Fields
64
65| Field | Type | Description |
66| ----- | ---- | ----------- |
67| `results` | array<object> | One result per query, in the same order as the request |
68| `results[].country` | string | ISO 3166-1 alpha-2 country code |
69| `results[].year` | integer | Year queried |
70| `results[].found` | boolean | false when no holidays exist for that country/year combination |
71| `results[].holidays` | array<object> | List of holidays. Omitted when found is false. |
72| `results[].total` | integer | Number of holidays. Omitted when found is false. |
73| `total` | integer | Total number of results (equals the number of queries sent) |
74
75## Errors
76
77- `400` **bad_request** — Malformed request body
78- `422` **validation_failed** — queries is missing, empty, exceeds 50 items, or contains invalid country codes or years
gabrielmoreira