Endpoint
POST https://requiems.xyz/v1/systems/location/resolve
Resolve Location
Resolve an address or coordinates into a full location profile — city, country, timezone, UTC offset, current time, working days this month, and next holiday.
Parameters
| Name |
Type |
Required |
Location |
Description |
address |
string |
no |
body |
Human-readable address string to geocode. Either address or coordinates is required. |
coordinates |
object |
no |
body |
Coordinates object for reverse geocoding. Either address or coordinates is required. Shape: {lat: float, lng: float} |
country_code |
string |
no |
body |
ISO 3166-1 alpha-2 country code hint. Overrides the geocoder-inferred country code when provided. |
Request Example
{
"address": "Alexanderplatz 1, Berlin",
"country_code": "DE"
}
Response Example
{
"data": {
"address": "Alexanderplatz 1, 10178 Berlin, Germany",
"city": "Berlin",
"country": "Germany",
"country_code": "DE",
"coordinates": {
"lat": 52.5219,
"lng": 13.4132
},
"timezone": "Europe/Berlin",
"utc_offset": "+02:00",
"current_time": "2026-06-15T14:32:00+02:00",
"is_holiday_today": false,
"working_days_this_month": 21,
"next_holiday": {
"date": "2026-10-03",
"name": "German Unity Day",
"type": "national"
},
"flags": []
},
"metadata": {
"timestamp": "2026-01-01T00:00:00Z"
}
}
Response Fields
| Field |
Type |
Description |
address |
string |
Normalized full address returned by the geocoder |
city |
string |
City name |
country |
string |
Full country name |
country_code |
string |
ISO 3166-1 alpha-2 country code |
coordinates |
object |
Resolved lat/lng coordinates |
timezone |
string |
IANA timezone identifier (e.g. Europe/Berlin). Null when timezone resolution fails. |
utc_offset |
string |
UTC offset string (e.g. +02:00). Null when timezone resolution fails. |
current_time |
string |
Current local time in RFC3339 format. Null when timezone resolution fails. |
is_holiday_today |
boolean |
True when today is a public holiday in the resolved country |
working_days_this_month |
integer |
Number of working days (excluding weekends and public holidays) in the current calendar month |
next_holiday |
object |
Next public holiday within 90 days. Shape: {date: YYYY-MM-DD, name: string, type: national} |
flags |
array |
Non-fatal warnings. Possible values: timezone_unavailable, calendar_unavailable |
Errors
undefined 422 — Neither address nor coordinates was providedundefined 422 — Geocoding service was unavailableundefined 401 — Missing or invalid API key
1---2name: global-data-post-resolve3description: Resolve an address or coordinates into a full location profile — city, country, timezone, UTC offset, current time, working days this month, and next holiday.4---5
6## Endpoint
7
8**POST https://requiems.xyz/v1/systems/location/resolve**
9
10## Resolve Location
11
12Resolve an address or coordinates into a full location profile — city, country, timezone, UTC offset, current time, working days this month, and next holiday.
13
14## Parameters
15
16| Name | Type | Required | Location | Description |
17| ---- | ---- | -------- | -------- | ----------- |
18| `address` | string | no | body | Human-readable address string to geocode. Either address or coordinates is required. |
19| `coordinates` | object | no | body | Coordinates object for reverse geocoding. Either address or coordinates is required. Shape: {lat: float, lng: float} |
20| `country_code` | string | no | body | ISO 3166-1 alpha-2 country code hint. Overrides the geocoder-inferred country code when provided. |
21
22## Request Example
23
24```json
25{
26 "address": "Alexanderplatz 1, Berlin",
27 "country_code": "DE"
28}
29```
30
31## Response Example
32
33```json
34{
35 "data": {
36 "address": "Alexanderplatz 1, 10178 Berlin, Germany",
37 "city": "Berlin",
38 "country": "Germany",
39 "country_code": "DE",
40 "coordinates": {
41 "lat": 52.5219,
42 "lng": 13.4132
43 },
44 "timezone": "Europe/Berlin",
45 "utc_offset": "+02:00",
46 "current_time": "2026-06-15T14:32:00+02:00",
47 "is_holiday_today": false,
48 "working_days_this_month": 21,
49 "next_holiday": {
50 "date": "2026-10-03",
51 "name": "German Unity Day",
52 "type": "national"
53 },
54 "flags": []
55 },
56 "metadata": {
57 "timestamp": "2026-01-01T00:00:00Z"
58 }
59}
60```
61
62## Response Fields
63
64| Field | Type | Description |
65| ----- | ---- | ----------- |
66| `address` | string | Normalized full address returned by the geocoder |
67| `city` | string | City name |
68| `country` | string | Full country name |
69| `country_code` | string | ISO 3166-1 alpha-2 country code |
70| `coordinates` | object | Resolved lat/lng coordinates |
71| `timezone` | string | IANA timezone identifier (e.g. Europe/Berlin). Null when timezone resolution fails. |
72| `utc_offset` | string | UTC offset string (e.g. +02:00). Null when timezone resolution fails. |
73| `current_time` | string | Current local time in RFC3339 format. Null when timezone resolution fails. |
74| `is_holiday_today` | boolean | True when today is a public holiday in the resolved country |
75| `working_days_this_month` | integer | Number of working days (excluding weekends and public holidays) in the current calendar month |
76| `next_holiday` | object | Next public holiday within 90 days. Shape: {date: YYYY-MM-DD, name: string, type: national} |
77| `flags` | array<string> | Non-fatal warnings. Possible values: timezone_unavailable, calendar_unavailable |
78
79## Errors
80
81- `undefined` **422** — Neither address nor coordinates was provided
82- `undefined` **422** — Geocoding service was unavailable
83- `undefined` **401** — Missing or invalid API key
gabrielmoreira