Developer docs for the tax data and its calculator
How to load a signed Octroi release, quote a stay's accommodation and city taxes to the cent, resolve a place and fetch releases over HTTP.
Octroi is two things that ship together: a dataset of European accommodation and city taxes, and a calculator that prices a stay against it. The data is published as signed releases. The calculator is a TypeScript library with no Node dependency, so it runs on a server or in a browser, and it never calls out to anything: you hand it a release and a stay, it hands back the taxes.
The data
A release holds one file per country. Each file lists the country's jurisdictions (regions, municipalities, associations and zones, with their LAU, NUTS and ISO codes), the charges each one levies, every dated version of each charge with its rates and exemptions, and the evidence behind it all.
Every piece of evidence is a verbatim quote from a published source, with an English translation where the source is in another language, the publisher, the URL and the date it was checked. Every rate, exemption and version cites at least one.
Twelve countries are live: Austria, Bulgaria, Croatia, Cyprus, Czechia, France, Germany, Greece, Italy, Portugal, Romania and Spain. Coverage says what that means for a given town.
The calculator
The calculator has two functions:
quoteprices a stay: a place, arrival and departure dates, rooms and guests, and optionally the room price. It returns one line per charge and room, each night it applies to, the amount in integer minor units, the law version and the evidence it rests on. See Quote a stay.resolvesays which charges apply to a place on a date and what their rates are, with no stay and no money. See Resolve a place.
Neither guesses. When the data cannot price something, the answer says so in unknowns and the quote's status is partial; when it needs the room price, the status is price_required.
The calculator ships with the licence. The samples in these docs import it from ./calculator.
Releases and signatures
A release is named by its date, such as 2026-10-11, and never changes once published. Its manifest.json names every file in it with a SHA-256 hash and size, and manifest.json.sig is an Ed25519 signature over the manifest's bytes. Check the signature, then each file's hash, and you know the files are the ones Octroi published. See Releases and signatures.
Where to go next
- Quickstart: load a release and quote a three-night stay in Barcelona.
- Quote a stay: the request and every field of the answer.
- Resolve a place: by jurisdiction id or by LAU code.
- Releases and signatures: release ids, the manifest, verifying the signature, conformance vectors.
- Coverage and unknowns: the twelve countries, and how a quote says what it doesn't know.
- Tokens and HTTP delivery: fetching releases with a bearer token.