# castomAPI Data

> Free, zero-authentication public reference data API: 34M+ standardized records
> across geography, languages, currencies, logistics, religion, automotive and
> global standards. JSON only. No key, no signup. OpenAPI 3.0 spec: /openapi.json
> (also /docs/json). Human-readable docs: /docs.

Base URL: https://data.castomapi.com

## Response envelope
Every success: {"status":"success","data":...} plus optional "count", "lang"
(the resolved language of localized fields) and "nextCursor" (opaque; pass back
as ?cursor= for the next page — never construct one yourself).
Errors: {"status":"error","code":"...","message":"..."} with a matching HTTP
status. 404 means the entity does not exist OR nothing was published for that
key (e.g. exchange rates on a weekend); 400 means a parameter failed its shape.

## Ground rules an agent should know before calling
- Path parameters are normalized: language tags fold to lowercase, entity codes
  to uppercase, and the NORMALIZED value is echoed back — /v1/countries/en/pl
  works and answers with "lang":"en".
- Search endpoints need at least 3 letters/digits in q (trigram index); fewer
  is a 400, not an empty result.
- Rate limit: 600 requests / 60s per client. Success responses are edge-cached
  up to 7 days — identical repeat calls are cheap and encouraged.
- Localization falls back to English per field. Currencies, timezones and
  demonyms are genuinely multilingual; country names are English-only upstream.
- Scripture book codes are OSIS-style short codes (GEN, EXO, MAT), NOT full
  names; edition ids are `source:shortTitle` (e.g. getbible:kjv). Filter
  editions on hasText:true before fetching chapters — catalogue entries without
  ingested text answer 404.
- VINs must match ^[A-HJ-NPR-Z0-9]{17}$ (uppercase, no I/O/Q per ISO 3779).
- Exchange rates: ECB reference rates, base EUR, business days only —
  /on/{date} answers 404 for weekends/holidays; cross-rates are triangulated
  through EUR, not market quotes. XXX is a real ISO 4217 code ("no currency")
  and answers 200.
- Coordinates: /v1/cities/nearby orders by distanceKm (great-circle).

## Time & Global Standards
- GET /health — Service Health Check
  e.g. /health — Liveness plus which optional corpora this deployment loaded
  e.g. /health — countries is the probe: a non-zero count proves the DB answered
  e.g. /health — places:true means the 13.4M-row GeoNames corpus is mounted
  e.g. /health — scripture:true means /v1/scripture/* is served, not 404
  e.g. /health — The only endpoint outside the success envelope - flat object, no wrapper
- GET /v1/timezones — Get All Timezones (English Default)
  e.g. /v1/timezones — Every IANA timezone
  e.g. /v1/timezones — utcOffset is the current offset, DST included
  e.g. /v1/timezones — Join target for /v1/cities.timezone
  e.g. /v1/timezones — IANA identifiers - Europe/Warsaw, not CET
  e.g. /v1/timezones — The largest single reference list here - compresses about 10x
- GET /v1/timezones/{lang} — Get All Timezones by Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/timezones/pl — Timezone names in Polish
  e.g. /v1/timezones/de — German
  e.g. /v1/timezones/ja — Japanese
  e.g. /v1/timezones/fr — French
  e.g. /v1/timezones/es — Spanish
- GET /v1/calling-codes/{countryCode} — Get E.164 Calling Prefix & Area Codes by Country. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code.
  e.g. /v1/calling-codes/PL — Poland is +48
  e.g. /v1/calling-codes/US — United States is +1
  e.g. /v1/calling-codes/JP — Japan is +81
  e.g. /v1/calling-codes/BR — Brazil is +55
  e.g. /v1/calling-codes/IN — India is +91
- GET /v1/holidays/{countryCode}/{year} — Get National & Bank Holidays by Country and Year. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; year (path, required) — Calendar year.
  e.g. /v1/holidays/PL/2025 — Polish public holidays for 2025
  e.g. /v1/holidays/US/2025 — United States
  e.g. /v1/holidays/JP/2025 — Japan
  e.g. /v1/holidays/DE/2026 — Germany, next year
  e.g. /v1/holidays/BR/2025 — Brazil
- GET /v1/units — Get All Measurement Units (UCUM)
  e.g. /v1/units — Every unit of measurement, all categories
  e.g. /v1/units — category groups them - length, mass, energy
  e.g. /v1/units — Carries conversion factors to the SI base unit
  e.g. /v1/units — Includes non-SI units still in real use
  e.g. /v1/units — Compresses about 10x - one of the largest bodies here
- GET /v1/units/{category} — Get Measurement Units by Category. Params: category (path, ^[A-Za-z][A-Za-z_ -]{0,31}$, required) — Unit category (e.g. length, mass, volume, temperature).
  e.g. /v1/units/length — Length units
  e.g. /v1/units/mass — Mass units
  e.g. /v1/units/energy — Energy units
  e.g. /v1/units/area — Area units
  e.g. /v1/units/pressure — Pressure units

## Geographic & Places
- GET /v1/continents — Get Continents (English Default)
  e.g. /v1/continents — All seven continents, default English
  e.g. /v1/continents — code is the two-letter continent code used by /v1/countries
  e.g. /v1/continents — Smallest reference list in the API - useful as a connectivity check
  e.g. /v1/continents — No parameters: the whole set every time
  e.g. /v1/continents — Cached for a week at the edge, like every /v1 reference route
- GET /v1/continents/{lang} — Get Continents by Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/continents/pl — Continent names in Polish
  e.g. /v1/continents/ja — Japanese - non-Latin script, returned unescaped as UTF-8
  e.g. /v1/continents/es — Spanish
  e.g. /v1/continents/ar — Arabic - right-to-left text
  e.g. /v1/continents/EN — Language tags are normalised DOWN: EN answers as lang:en
- GET /v1/countries — Get All Countries (English Default)
  e.g. /v1/countries — All 250 countries and territories, English
  e.g. /v1/countries — Includes ISO 3166-1 alpha-2, alpha-3 and numeric codes
  e.g. /v1/countries — continent links each row to /v1/continents
  e.g. /v1/countries — The count field is the authoritative total - 250
  e.g. /v1/countries — Territories are included, not just UN member states
- GET /v1/countries/{lang} — Get All Countries by Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/countries/pl — All countries with Polish names
  e.g. /v1/countries/de — German
  e.g. /v1/countries/fr — French
  e.g. /v1/countries/zh — Chinese
  e.g. /v1/countries/pt — Portuguese
- GET /v1/countries/{lang}/{code} — Get Country by Code & Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code; code (path, ^[A-Za-z]{2,3}$, required) — ISO 3166-1 alpha-2 or alpha-3 country code.
  e.g. /v1/countries/en/PL — Poland in English
  e.g. /v1/countries/pl/PL — Poland in Polish - Polska
  e.g. /v1/countries/en/pl — Entity codes are normalised UP: lowercase pl works
  e.g. /v1/countries/ja/JP — Japan in Japanese
  e.g. /v1/countries/es/BR — Brazil in Spanish
- GET /v1/subdivisions/{countryCode} — Get Subdivisions by Country (English Default). Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code.
  e.g. /v1/subdivisions/PL — Polish voivodeships, ISO 3166-2
  e.g. /v1/subdivisions/US — US states and territories
  e.g. /v1/subdivisions/JP — Japanese prefectures
  e.g. /v1/subdivisions/DE — German Bundeslander
  e.g. /v1/subdivisions/BR — Brazilian states
- GET /v1/subdivisions/{countryCode}/{lang} — Get Subdivisions by Country & Language Path. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/subdivisions/PL/pl — Voivodeship names in Polish
  e.g. /v1/subdivisions/JP/ja — Prefecture names in Japanese
  e.g. /v1/subdivisions/DE/de — Bundeslander in German
  e.g. /v1/subdivisions/ES/es — Spanish autonomous communities in Spanish
  e.g. /v1/subdivisions/IT/it — Italian regions in Italian
- GET /v1/cities/search — Search Cities & Populated Places. Params: q (query, required) — Search query string (e.g. Warsaw, Los Angeles); limit (query).
  e.g. /v1/cities/search?q=Warsaw — Plain name search
  e.g. /v1/cities/search?q=krakow — Diacritics are folded on BOTH sides - krakow finds Krakow
  e.g. /v1/cities/search?q=Wien — Endonym: Wien finds Vienna
  e.g. /v1/cities/search?q=Tokyo&limit=5 — limit caps the result set
  e.g. /v1/cities/search?q=Sao%20Paulo&limit=3 — Multi-word terms - space MUST be percent-encoded, a literal space breaks the query string
- GET /v1/cities/nearby — Find Cities Near a Point. Params: lat (query, required) — Latitude in decimal degrees; lon (query, required) — Longitude in decimal degrees; radius (query) — Search radius in kilometres; limit (query).
  e.g. /v1/cities/nearby?lat=52.2297&lon=21.0122 — Cities near Warsaw
  e.g. /v1/cities/nearby?lat=35.6762&lon=139.6503&radius=50 — Near Tokyo, 50 km radius
  e.g. /v1/cities/nearby?lat=40.7128&lon=-74.0060&limit=5 — Near New York, capped at 5
  e.g. /v1/cities/nearby?lat=-33.8688&lon=151.2093&radius=100 — Near Sydney - southern hemisphere, negative latitude
  e.g. /v1/cities/nearby?lat=48.8566&lon=2.3522&radius=25&limit=10 — Near Paris, both radius and limit
- GET /v1/cities/country/{countryCode} — Get Cities by Country Code. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; limit (query); cursor (query, ^[A-Za-z0-9_-]{1,256}$) — Opaque cursor from a previous response's nextCursor; do not construct one.
  e.g. /v1/cities/country/PL — Cities in Poland
  e.g. /v1/cities/country/JP?limit=10 — Japan, first ten
  e.g. /v1/cities/country/BR?limit=5 — Brazil
  e.g. /v1/cities/country/DE?limit=25 — Germany - a larger page
  e.g. /v1/cities/country/IS — Iceland - a small set that fits in one page
- GET /v1/cities/{id} — Get a City by GeoNames ID. Params: id (path, required) — GeoNames geonameid.
  e.g. /v1/cities/756135 — Warsaw, Poland - GeoNames id 756135
  e.g. /v1/cities/4927854 — Warsaw, United States - same name, different city
  e.g. /v1/cities/5143282 — Warsaw, New York
  e.g. /v1/cities/756135 — Response carries population, coordinates and timezone
  e.g. /v1/cities/756135 — timezone joins to /v1/timezones
- GET /v1/places/search — Search All Geographic Features. Params: q (query, required) — Search query (e.g. Everest, Danube, Warsaw); class (query, ^[AHLPRSTUVahlprstuv]$) — GeoNames feature class: A admin, H water, L parks, P populated, R roads, S spots, T terrain, U undersea, V forest; limit (query).
  e.g. /v1/places/search?q=Kyoto — Any populated place, not just cities
  e.g. /v1/places/search?q=Kyoto&class=P — class=P restricts to populated places
  e.g. /v1/places/search?q=Kyoto&class=A — class=A restricts to administrative divisions
  e.g. /v1/places/search?q=Everest&limit=5 — class T features - mountains - are in here too
  e.g. /v1/places/search?q=Warszawa&limit=3 — Endonym spelling of Warsaw
- GET /v1/places/country/{countryCode} — Get Geographic Features by Country. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; class (query, ^[AHLPRSTUVahlprstuv]$) — GeoNames feature class: A admin, H water, L parks, P populated, R roads, S spots, T terrain, U undersea, V forest; limit (query); cursor (query, ^[A-Za-z0-9_-]{1,256}$) — Opaque cursor from a previous response's nextCursor; do not construct one.
  e.g. /v1/places/country/PL?limit=10 — Every feature class in Poland
  e.g. /v1/places/country/JP?class=P&limit=10 — Populated places in Japan only
  e.g. /v1/places/country/CH?class=T&limit=10 — Terrain features in Switzerland - mountains, passes
  e.g. /v1/places/country/NO?class=H&limit=10 — Hydrographic features in Norway - fjords, lakes
  e.g. /v1/places/country/IS?limit=5 — Iceland
- GET /v1/places/{id}/names — Get Alternate Names for a Place. Params: id (path, required) — GeoNames geonameid; lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code; limit (query).
  e.g. /v1/places/6695624/names — Every alternate name recorded for Warsaw
  e.g. /v1/places/6695624/names?lang=pl — Only the Polish forms
  e.g. /v1/places/1857910/names?lang=ja — Kyoto has Japanese forms; Warsaw (6695624) does not - lang is per-place, not universal
  e.g. /v1/places/1857910/names?limit=20 — Kyoto, first twenty
  e.g. /v1/places/6695624/names?limit=5 — NULL-language rows sort FIRST, matching the source
- GET /v1/places/{id}/parents — Get the Administrative Breadcrumb for a Place. Params: id (path, required) — GeoNames geonameid; lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code.
  e.g. /v1/places/6695624/parents — Administrative chain above Warsaw
  e.g. /v1/places/6695624/parents?lang=pl — The same chain, Polish names
  e.g. /v1/places/1857910/parents — Kyoto up to Japan
  e.g. /v1/places/1857910/parents?lang=ja — Kyoto chain in Japanese
  e.g. /v1/places/756135/parents — Works for city ids too - one id space
- GET /v1/places/{id} — Get a Geographic Feature by GeoNames ID. Params: id (path, required) — GeoNames geonameid.
  e.g. /v1/places/6695624 — Warsaw as a GeoNames place
  e.g. /v1/places/1857910 — Kyoto, Japan
  e.g. /v1/places/1857907 — Kyoto Prefecture - the admin division, feature class A
  e.g. /v1/places/756135 — Warsaw again via its city id
  e.g. /v1/places/6695624 — Carries featureClass and featureCode, unlike /v1/cities
- GET /v1/postal-codes/search — Search Postal & Zip Codes. Params: q (query, required) — Search query string (e.g. 90210, Beverly Hills); limit (query).
  e.g. /v1/postal-codes/search?q=Warszawa — Postal codes by place name
  e.g. /v1/postal-codes/search?q=Krakow&limit=10 — Krakow, ten results
  e.g. /v1/postal-codes/search?q=Berlin&limit=5 — Berlin
  e.g. /v1/postal-codes/search?q=Kyoto&limit=5 — Kyoto
  e.g. /v1/postal-codes/search?q=Lisboa&limit=5 — Lisbon, endonym spelling
- GET /v1/postal-codes/{countryCode}/{postalCode} — Lookup Postal Code by Country. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; postalCode (path, ^[A-Za-z0-9][A-Za-z0-9 \-]{0,15}$, required) — Postal or ZIP code.
  e.g. /v1/postal-codes/PL/00-002 — A central Warsaw code
  e.g. /v1/postal-codes/US/10001 — Manhattan
  e.g. /v1/postal-codes/DE/10115 — Berlin Mitte
  e.g. /v1/postal-codes/FR/75001 — Paris 1er
  e.g. /v1/postal-codes/JP/100-0001 — Chiyoda, Tokyo - hyphenated format

## Linguistics & Localization
- GET /v1/languages — Get Languages (English Default)
  e.g. /v1/languages — Every language the API knows
  e.g. /v1/languages — isRtl marks right-to-left scripts
  e.g. /v1/languages — code is the tag accepted by every {lang} path segment
  e.g. /v1/languages — Includes historical and constructed languages, not only living ones
  e.g. /v1/languages — Join to /v1/scripts through the script field
- GET /v1/languages/{lang} — Get Languages by Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/languages/pl — Polish
  e.g. /v1/languages/ar — Arabic - isRtl is true
  e.g. /v1/languages/ja — Japanese
  e.g. /v1/languages/sw — Swahili
  e.g. /v1/languages/EN — Normalised down - EN resolves to en
- GET /v1/dialects — Get Dialects (English Default)
  e.g. /v1/dialects — Regional varieties across all languages
  e.g. /v1/dialects — Each row links to its parent language code
  e.g. /v1/dialects — Useful for locale pickers that need more than a language tag
  e.g. /v1/dialects — No parameters - the full list
  e.g. /v1/dialects — Pair with /v1/locales for the region half
- GET /v1/dialects/{lang} — Get Dialects by Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/dialects/en — English varieties
  e.g. /v1/dialects/es — Spanish varieties
  e.g. /v1/dialects/ar — Arabic varieties
  e.g. /v1/dialects/de — German varieties
  e.g. /v1/dialects/zh — Chinese varieties
- GET /v1/scripts — Get Writing Systems & Scripts (ISO 15924)
  e.g. /v1/scripts — ISO 15924 writing systems
  e.g. /v1/scripts — direction distinguishes LTR from RTL
  e.g. /v1/scripts — Join target for /v1/languages.script
  e.g. /v1/scripts — Includes historical scripts
  e.g. /v1/scripts — Four-letter codes: Latn, Cyrl, Arab, Hans
- GET /v1/locales — Get CLDR Locales
  e.g. /v1/locales — Language-region combinations
  e.g. /v1/locales — The shape most i18n libraries expect - pl-PL, en-US
  e.g. /v1/locales — Region halves join to /v1/countries
  e.g. /v1/locales — Language halves join to /v1/languages
  e.g. /v1/locales — No parameters - the full matrix
- GET /v1/exonyms/search — Search Multilingual Exonyms. Params: q (query, required) — Search query (e.g. Varsovie, Warsaw); limit (query).
  e.g. /v1/exonyms/search?q=Pol — What other languages call Poland
  e.g. /v1/exonyms/search?q=Germ&limit=10 — Germany
  e.g. /v1/exonyms/search?q=Japan&limit=10 — Japan
  e.g. /v1/exonyms/search?q=Deutschland&limit=5 — What other languages call Germany
  e.g. /v1/exonyms/search?q=Roma&limit=5 — Rome by its Italian name
- GET /v1/demonyms/{countryCode} — Get Demonyms for Country (English Default). Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code.
  e.g. /v1/demonyms/PL — What a person from Poland is called
  e.g. /v1/demonyms/JP — Japan
  e.g. /v1/demonyms/BR — Brazil
  e.g. /v1/demonyms/DE — Germany
  e.g. /v1/demonyms/EG — Egypt
- GET /v1/demonyms/{countryCode}/{lang} — Get Demonyms for Country by Language Path. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/demonyms/PL/pl — Polish demonym in Polish - Polacy
  e.g. /v1/demonyms/DE/de — German in German
  e.g. /v1/demonyms/JP/ja — Japanese in Japanese
  e.g. /v1/demonyms/FR/fr — French in French
  e.g. /v1/demonyms/BR/pt — Brazilian in Portuguese

## Financials & Commerce
- GET /v1/currencies — Get All Currencies (English Default)
  e.g. /v1/currencies — Every ISO 4217 currency
  e.g. /v1/currencies — Includes historical currencies, not only circulating ones
  e.g. /v1/currencies — code is the join key for /v1/exchange-rates
  e.g. /v1/currencies — Carries minor-unit digits for correct rounding
  e.g. /v1/currencies — XXX and XAU are present - reserved and metal codes are real ISO codes
- GET /v1/currencies/{lang} — Get All Currencies by Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code.
  e.g. /v1/currencies/pl — Currency names in Polish
  e.g. /v1/currencies/de — German
  e.g. /v1/currencies/ja — Japanese
  e.g. /v1/currencies/fr — French
  e.g. /v1/currencies/es — Spanish
- GET /v1/currencies/{lang}/{code} — Get Currency by Code & Language Path. Params: lang (path, ^[A-Za-z]{2}$, required) — ISO 639-1 language code; code (path, ^[A-Za-z]{3}$, required) — ISO 4217 currency code.
  e.g. /v1/currencies/pl/PLN — The zloty in Polish - zloty polski
  e.g. /v1/currencies/en/JPY — Japanese yen in English
  e.g. /v1/currencies/en/EUR — Euro
  e.g. /v1/currencies/de/CHF — Swiss franc in German
  e.g. /v1/currencies/en/XXX — XXX is a real reserved code and answers 200, not 404
- GET /v1/currency-rules/{currencyCode} — Get Currency Formatting Rules & Precision. Params: currencyCode (path, ^[A-Za-z]{3}$, required) — ISO 4217 currency code.
  e.g. /v1/currency-rules/JPY — Yen has no minor unit - zero decimal places
  e.g. /v1/currency-rules/USD — Two decimal places
  e.g. /v1/currency-rules/PLN — Polish zloty
  e.g. /v1/currency-rules/BHD — Bahraini dinar - three decimal places
  e.g. /v1/currency-rules/EUR — Euro formatting rules
- GET /v1/address-schemas/{countryCode} — Get Country Postal Address Layout Schema. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code.
  e.g. /v1/address-schemas/PL — How to lay out and validate a Polish address
  e.g. /v1/address-schemas/US — United States, with state and ZIP
  e.g. /v1/address-schemas/JP — Japan - prefecture-first ordering
  e.g. /v1/address-schemas/DE — Germany
  e.g. /v1/address-schemas/GB — United Kingdom postcode rules
- GET /v1/exchange-rates/latest — Get Latest ECB Reference Rates (base EUR)
  e.g. /v1/exchange-rates/latest — Most recent ECB reference rates, base EUR
  e.g. /v1/exchange-rates/latest — Refreshed daily from the ECB feed
  e.g. /v1/exchange-rates/latest — 41 currencies, base EUR by construction
  e.g. /v1/exchange-rates/latest — date tells you which business day this is
  e.g. /v1/exchange-rates/latest — Weekends and holidays fall back to the last published day
- GET /v1/exchange-rates/latest/{currency} — Get Latest ECB Reference Rate for One Currency. Params: currency (path, ^[A-Za-z]{3}$, required) — ISO 4217 currency code.
  e.g. /v1/exchange-rates/latest/PLN — Latest zloty rate
  e.g. /v1/exchange-rates/latest/USD — US dollar
  e.g. /v1/exchange-rates/latest/JPY — Japanese yen
  e.g. /v1/exchange-rates/latest/GBP — Pound sterling
  e.g. /v1/exchange-rates/latest/CHF — Swiss franc
- GET /v1/exchange-rates/on/{date} — Get All ECB Reference Rates for a Specific Date. Params: date (path, ^\d{4}-\d{2}-\d{2}$, required) — Date in YYYY-MM-DD.
  e.g. /v1/exchange-rates/on/2025-01-02 — Rates on a specific business day
  e.g. /v1/exchange-rates/on/2024-12-31 — Year end 2024
  e.g. /v1/exchange-rates/on/2020-03-16 — The COVID crash week
  e.g. /v1/exchange-rates/on/2015-01-15 — The day the Swiss franc peg broke
  e.g. /v1/exchange-rates/on/1999-01-04 — The first day the ECB published - the series starts here
- GET /v1/exchange-rates/{from}/{to} — Convert Between Two Currencies (triangulated through EUR). Params: from (path, ^[A-Za-z]{3}$, required) — ISO 4217 currency code; to (path, ^[A-Za-z]{3}$, required) — ISO 4217 currency code; date (query, ^\d{4}-\d{2}-\d{2}$) — Date in YYYY-MM-DD.
  e.g. /v1/exchange-rates/EUR/PLN — Euro to zloty
  e.g. /v1/exchange-rates/USD/JPY — Cross rate - triangulated through EUR
  e.g. /v1/exchange-rates/GBP/USD — Cable
  e.g. /v1/exchange-rates/PLN/EUR — Inverse direction
  e.g. /v1/exchange-rates/USD/PLN?date=2025-01-02 — A cross rate on a given day
- GET /v1/exchange-rates/history/{currency} — Get ECB Reference Rate History for One Currency. Params: currency (path, ^[A-Za-z]{3}$, required) — ISO 4217 currency code; from (query, ^\d{4}-\d{2}-\d{2}$, required) — Date in YYYY-MM-DD; to (query, ^\d{4}-\d{2}-\d{2}$, required) — Date in YYYY-MM-DD.
  e.g. /v1/exchange-rates/history/USD?from=2025-01-01&to=2025-01-31 — One month of dollar rates
  e.g. /v1/exchange-rates/history/PLN?from=2024-01-01&to=2024-12-31 — A full year of zloty
  e.g. /v1/exchange-rates/history/JPY?from=2025-06-01&to=2025-06-30 — June 2025, yen
  e.g. /v1/exchange-rates/history/GBP?from=2020-03-01&to=2020-04-30 — Sterling across the COVID crash
  e.g. /v1/exchange-rates/history/CHF?from=2015-01-01&to=2015-02-28 — Franc around the peg break

## Logistics & Infrastructure
- GET /v1/airports/search — Search Airports & Aviation Hubs. Params: q (query, required) — Search query (e.g. JFK, Warsaw, EPWA); limit (query).
  e.g. /v1/airports/search?q=Chopin — Warsaw Chopin by name
  e.g. /v1/airports/search?q=Heathrow&limit=5 — London Heathrow
  e.g. /v1/airports/search?q=Narita&limit=5 — Tokyo Narita
  e.g. /v1/airports/search?q=Frankfurt&limit=10 — Frankfurt - several matches
  e.g. /v1/airports/search?q=Kennedy&limit=5 — JFK by its full name
- GET /v1/airports/{countryCode} — Get Airports by Country Code. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; limit (query); cursor (query, ^[A-Za-z0-9_-]{1,256}$) — Opaque cursor from a previous response's nextCursor; do not construct one.
  e.g. /v1/airports/PL — Airports in Poland
  e.g. /v1/airports/JP?limit=10 — Japan
  e.g. /v1/airports/US?limit=10 — United States - a long list, page it
  e.g. /v1/airports/BR?limit=10 — Brazil
  e.g. /v1/airports/IS — Iceland - small enough for one page
- GET /v1/seaports/search — Search Seaports & Trade Locations (UN/LOCODE). Params: q (query, required) — Search query (e.g. PLGDN, Gdansk, Hamburg); limit (query).
  e.g. /v1/seaports/search?q=Rotterdam — Europe largest port
  e.g. /v1/seaports/search?q=Shanghai&limit=5 — Shanghai
  e.g. /v1/seaports/search?q=Gdansk&limit=5 — Gdansk - diacritics folded
  e.g. /v1/seaports/search?q=Singapore&limit=5 — Singapore
  e.g. /v1/seaports/search?q=Hamburg&limit=5 — Hamburg
- GET /v1/seaports/{countryCode} — Get Seaports by Country Code. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; limit (query); cursor (query, ^[A-Za-z0-9_-]{1,256}$) — Opaque cursor from a previous response's nextCursor; do not construct one.
  e.g. /v1/seaports/PL — Polish seaports
  e.g. /v1/seaports/NL?limit=10 — Netherlands
  e.g. /v1/seaports/JP?limit=10 — Japan
  e.g. /v1/seaports/GR?limit=10 — Greece - many islands, many ports
  e.g. /v1/seaports/NO?limit=10 — Norway

## Automotive
- GET /v1/vehicles/makes — List vehicle brands. Params: country (query, ^[A-Za-z]{2}$) — ISO 3166-1 alpha-2 country code; limit (query); cursor (query, ^[A-Za-z0-9_-]{1,256}$) — Opaque cursor from a previous response's nextCursor; do not construct one.
  e.g. /v1/vehicles/makes?limit=10 — Vehicle manufacturers, first page
  e.g. /v1/vehicles/makes?country=JP&limit=10 — Japanese manufacturers
  e.g. /v1/vehicles/makes?country=DE&limit=10 — German manufacturers
  e.g. /v1/vehicles/makes?country=US&limit=10 — United States
  e.g. /v1/vehicles/makes?country=IT&limit=10 — Italy
- GET /v1/vehicles/makes/search — Search vehicle brands. Params: q (query, required); limit (query).
  e.g. /v1/vehicles/makes/search?q=Toyota — Toyota
  e.g. /v1/vehicles/makes/search?q=BMW — BMW
  e.g. /v1/vehicles/makes/search?q=Ford&limit=5 — Ford
  e.g. /v1/vehicles/makes/search?q=Volkswagen&limit=5 — Volkswagen
  e.g. /v1/vehicles/makes/search?q=Honda&limit=5 — Honda
- GET /v1/vehicles/makes/{id} — Get a vehicle brand by id. Params: id (path, required) — Numeric resource identifier; lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code.
  e.g. /v1/vehicles/makes/448 — Toyota - NHTSA make id 448
  e.g. /v1/vehicles/makes/452 — BMW
  e.g. /v1/vehicles/makes/460 — Ford
  e.g. /v1/vehicles/makes/474 — Honda
  e.g. /v1/vehicles/makes/482 — Volkswagen
- GET /v1/vehicles/makes/{id}/models — List models of a vehicle brand. Params: id (path, required) — Numeric resource identifier; lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code; limit (query).
  e.g. /v1/vehicles/makes/448/models — Every Toyota model - the largest of these
  e.g. /v1/vehicles/makes/452/models?limit=25 — BMW, first 25
  e.g. /v1/vehicles/makes/460/models?limit=25 — Ford
  e.g. /v1/vehicles/makes/474/models?limit=25 — Honda
  e.g. /v1/vehicles/makes/482/models?limit=25 — Volkswagen
- GET /v1/vehicles/models/search — Search vehicle models. Params: q (query, required); limit (query).
  e.g. /v1/vehicles/models/search?q=Corolla — Toyota Corolla and its variants
  e.g. /v1/vehicles/models/search?q=Golf&limit=10 — VW Golf
  e.g. /v1/vehicles/models/search?q=Mustang&limit=10 — Ford Mustang
  e.g. /v1/vehicles/models/search?q=Civic&limit=10 — Honda Civic
  e.g. /v1/vehicles/models/search?q=Series&limit=10 — BMW series naming
- GET /v1/vehicles/models/{id} — Get a vehicle model by id. Params: id (path, required) — Numeric resource identifier; lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code.
  e.g. /v1/vehicles/models/1011321631 — Toyota Corolla II
  e.g. /v1/vehicles/models/1092314244 — Toyota Corolla EX
  e.g. /v1/vehicles/models/1111445944 — Toyota GR Corolla
  e.g. /v1/vehicles/models/1011321631?lang=pl — The same model with Polish labels
  e.g. /v1/vehicles/models/1111445944?lang=de — German labels
- GET /v1/vehicles/manufacturers/{countryCode} — List vehicle manufacturers by country. Params: countryCode (path, ^[A-Za-z]{2}$, required) — ISO 3166-1 alpha-2 country code; limit (query).
  e.g. /v1/vehicles/manufacturers/JP?limit=10 — Japanese manufacturers
  e.g. /v1/vehicles/manufacturers/DE?limit=10 — German
  e.g. /v1/vehicles/manufacturers/US?limit=10 — United States
  e.g. /v1/vehicles/manufacturers/IT?limit=10 — Italian
  e.g. /v1/vehicles/manufacturers/KR?limit=10 — South Korean
- GET /v1/vehicles/wmi/{wmi} — Look up a World Manufacturer Identifier. Params: wmi (path, ^[A-HJ-NPR-Z0-9]{3}([A-HJ-NPR-Z0-9]{3})?$, required) — World Manufacturer Identifier (VIN characters 1-3, or 1-3 + 12-14).
  e.g. /v1/vehicles/wmi/JT2 — World Manufacturer Identifier JT2 - Toyota
  e.g. /v1/vehicles/wmi/WBA — BMW
  e.g. /v1/vehicles/wmi/1FA — Ford, United States
  e.g. /v1/vehicles/wmi/WVW — Volkswagen
  e.g. /v1/vehicles/wmi/JHM — Honda
- GET /v1/vehicles/vin/{vin} — Decode a VIN. Params: vin (path, ^[A-HJ-NPR-Z0-9]{17}$, required) — 17-character Vehicle Identification Number.
  e.g. /v1/vehicles/vin/JT2BF22K1W0123456 — Decode a Toyota VIN
  e.g. /v1/vehicles/vin/WBADT43452G296403 — A BMW VIN
  e.g. /v1/vehicles/vin/1FAFP404X1F123456 — A Ford VIN
  e.g. /v1/vehicles/vin/WVWZZZ1JZXW000001 — A Volkswagen VIN
  e.g. /v1/vehicles/vin/JHMCM56557C404453 — A Honda VIN

## Religion
- GET /v1/religions — List religions. Params: lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code.
  e.g. /v1/religions — Every religion tracked
  e.g. /v1/religions?lang=pl — Names in Polish
  e.g. /v1/religions?lang=ar — Names in Arabic
  e.g. /v1/religions?lang=ja — Names in Japanese
  e.g. /v1/religions?lang=es — Names in Spanish
- GET /v1/religions/{code} — Get a religion. Params: code (path, ^[a-z0-9][a-z0-9-]{0,63}$, required) — Lower-case slug identifier; lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code.
  e.g. /v1/religions/christianity — Christianity
  e.g. /v1/religions/islam — Islam
  e.g. /v1/religions/hinduism — Hinduism
  e.g. /v1/religions/buddhism — Buddhism
  e.g. /v1/religions/judaism?lang=pl — Judaism, Polish labels
- GET /v1/religions/{code}/denominations — List denominations of a religion. Params: code (path, ^[a-z0-9][a-z0-9-]{0,63}$, required) — Lower-case slug identifier; lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code.
  e.g. /v1/religions/christianity/denominations — Christian denominations
  e.g. /v1/religions/islam/denominations — Islamic branches
  e.g. /v1/religions/buddhism/denominations — Buddhist traditions
  e.g. /v1/religions/judaism/denominations — Jewish movements
  e.g. /v1/religions/hinduism/denominations?lang=en — Hindu traditions
- GET /v1/scripture/texts — List sacred texts and the reach of their edition catalogue
  e.g. /v1/scripture/texts — The scriptural corpora available
  e.g. /v1/scripture/texts — code is the key for /v1/scripture/texts/{code}/editions
  e.g. /v1/scripture/texts — Covers 17 traditions, not only the Abrahamic ones
  e.g. /v1/scripture/texts — hasText says whether verse text is actually loaded
  e.g. /v1/scripture/texts — verseCount is the loaded total per corpus
- GET /v1/scripture/texts/{textCode}/editions — List editions of a sacred text. Params: textCode (path, ^[a-z0-9][a-z0-9-]{0,63}$, required) — Lower-case slug identifier; lang (query, ^[A-Za-z]{2,3}$) — ISO 639-1 or ISO 639-3 language code; withText (query, boolean) — Only editions whose verses are ingested; limit (query).
  e.g. /v1/scripture/texts/bible/editions?limit=10 — Bible editions - 98 of them
  e.g. /v1/scripture/texts/quran/editions?limit=10 — Quran editions
  e.g. /v1/scripture/texts/bible/editions?lang=pl — Polish Bible editions
  e.g. /v1/scripture/texts/bible/editions?lang=de&limit=5 — German editions
  e.g. /v1/scripture/texts/bible/editions?withText=true&limit=5 — Only editions whose verse text is loaded
- GET /v1/prayers — List prayers. Params: lang (query, ^[A-Za-z]{2}$) — ISO 639-1 language code; religion (query, ^[a-z0-9][a-z0-9-]{0,63}$) — Lower-case slug identifier; category (query, ^[a-z0-9][a-z0-9-]{0,63}$) — Lower-case slug identifier.
  e.g. /v1/prayers?limit=10 — Prayers across traditions
  e.g. /v1/prayers?religion=buddhism&limit=10 — Buddhist prayers
  e.g. /v1/prayers?religion=christianity&limit=10 — Christian prayers
  e.g. /v1/prayers?religion=islam&limit=10 — Islamic prayers
  e.g. /v1/prayers?lang=en&limit=10 — English texts only
- GET /v1/prayers/search — Search prayer wording. Params: q (query, required); limit (query).
  e.g. /v1/prayers/search?q=refuge — Search prayer text
  e.g. /v1/prayers/search?q=father&limit=10 — father
  e.g. /v1/prayers/search?q=God&limit=10 — God
  e.g. /v1/prayers/search?q=mercy&limit=10 — mercy
  e.g. /v1/prayers/search?q=light&limit=5 — light
- GET /v1/prayers/{code}/{lang} — Get a prayer's wording in a language. Params: code (path, ^[a-z0-9][a-z0-9-]{0,63}$, required) — Lower-case slug identifier; lang (path, ^[A-Za-z]{2,3}$, required) — ISO 639-1 or ISO 639-3 language code.
  e.g. /v1/prayers/three-refuges/en — The Three Refuges in English
  e.g. /v1/prayers/heart-sutra/en — The Heart Sutra
  e.g. /v1/prayers/metta-sutta/en — The Metta Sutta
  e.g. /v1/prayers/nembutsu/en — The Nembutsu
  e.g. /v1/prayers/short-obligatory-prayer/en — The Bahai Short Obligatory Prayer
- GET /v1/prayer-times/methods — List salah calculation conventions
  e.g. /v1/prayer-times/methods — The twelve calculation methods
  e.g. /v1/prayer-times/methods — fajrAngle and ishaAngle differ per method
  e.g. /v1/prayer-times/methods — code is what /v1/prayer-times?method= accepts
  e.g. /v1/prayer-times/methods — MWL is the Muslim World League default
  e.g. /v1/prayer-times/methods — Regional methods: EGYPT, KARACHI, MAKKAH, TEHRAN
- GET /v1/prayer-times — Compute salah times for a place and date. Params: latitude (query, required) — Latitude in decimal degrees; longitude (query, required) — Longitude in decimal degrees; date (query, ^\d{4}-\d{2}-\d{2}$, required); method (query, ^[A-Za-z]{2,12}$); timezoneOffset (query); asrShadowFactor (query).
  e.g. /v1/prayer-times?latitude=52.2297&longitude=21.0122&date=2025-06-15 — Warsaw, midsummer
  e.g. /v1/prayer-times?latitude=21.4225&longitude=39.8262&date=2025-06-15&method=MAKKAH — Mecca, Makkah method
  e.g. /v1/prayer-times?latitude=30.0444&longitude=31.2357&date=2025-06-15&method=EGYPT — Cairo, Egyptian authority
  e.g. /v1/prayer-times?latitude=24.8607&longitude=67.0011&date=2025-06-15&method=KARACHI — Karachi
  e.g. /v1/prayer-times?latitude=41.0082&longitude=28.9784&date=2025-12-21&method=TURKEY — Istanbul at the winter solstice
- GET /v1/observances — List religious observances. Params: religion (query, ^[a-z0-9][a-z0-9-]{0,63}$) — Lower-case slug identifier.
  e.g. /v1/observances — Religious observances across all traditions
  e.g. /v1/observances?religion=christianity — Christian observances
  e.g. /v1/observances?religion=islam — Islamic observances
  e.g. /v1/observances?religion=judaism — Jewish observances
  e.g. /v1/observances?religion=hinduism — Hindu observances
- GET /v1/scripture/editions/{editionId}/{book}/{chapter} — Get a chapter of a scripture edition. Params: editionId (path, ^[a-z]+:[A-Za-z0-9._-]{1,64}$, required) — Scripture edition identifier, source-prefixed; book (path, ^[A-Z0-9]{1,3}$, required) — Canonical book code (USFM), or Q for the Qur'an; chapter (path, required) — Chapter number (surah for the Qur'an).
  e.g. /v1/scripture/editions/getbible:bkr/GEN/1 — Genesis 1 in the Czech Bible kralicka - 31 verses
  e.g. /v1/scripture/editions/getbible:bkr/JHN/3 — John 3
  e.g. /v1/scripture/editions/getbible:danish/GEN/1 — Genesis 1 in Danish
  e.g. /v1/scripture/editions/getbible:bkr/PSA/23 — Psalm 23
  e.g. /v1/scripture/editions/getbible:bkr/EXO/20 — Exodus 20 - book codes are OSIS-style GEN, not genesis
- GET /v1/scripture/search — Full-text search across ingested scripture. Params: q (query, required); limit (query).
  e.g. /v1/scripture/search?q=beginning — Full-text search across loaded verses
  e.g. /v1/scripture/search?q=light&limit=10 — Ten hits for light
  e.g. /v1/scripture/search?q=shepherd&limit=10 — shepherd
  e.g. /v1/scripture/search?q=wisdom&limit=10 — wisdom
  e.g. /v1/scripture/search?q=covenant&limit=5 — covenant

## Examples
- https://data.castomapi.com/v1/countries/pl/DE — Germany, localized fields in Polish where they exist
- https://data.castomapi.com/v1/cities/search?q=Warszawa — endonym search finds Warsaw
- https://data.castomapi.com/v1/exchange-rates/PLN/USD?date=2020-06-15 — historical cross-rate
- https://data.castomapi.com/v1/scripture/editions/getbible:kjv/GEN/1 — Genesis 1, KJV
- https://data.castomapi.com/v1/prayer-times?latitude=21.4225&longitude=39.8262&date=2026-06-21&method=MWL&timezoneOffset=3

Generated by bin/generate-llms.php from spec/openapi.json — regenerate both
together after any route change; never hand-edit the endpoint list above.