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