Главная API Reference Overview

OpenTax REST API Reference

The OpenTax REST API provides sub-millisecond sales tax rate lookups, multi-jurisdiction breakdown calculations, spatial GPS lookups, and auto-complete search across all 50 US states, 41,000+ ZIP codes, and SST compliance regions.

Sub-ms TTFB (Go Engine)

Zero-Auth Free Tier

50 States + 41k ZIPs

SST Certified Multi-Tier

Production Base URL HTTP/1.1 & HTTP/2

HTTPS https://opentaxus.com/api/v1

Authentication

The public endpoints of OpenTax are free to use without requiring an API key. For enterprise integrations, rate limit exemptions, or dedicated SLA instances, include your token in the Authorization request header:

Authorization: Bearer YOUR_API_KEY

Multi-Language Localization (i18n)

All endpoints accept an optional lang query parameter to return localized entity names for states, counties, and cities.

Language Code (lang)	Language Name	Example Output
`en` Default	🇺🇸 English (US)	California, Los Angeles
`zh-hans` / `zh` / `zh-cn`	🇨🇳 简体中文 (Simplified Chinese)	加利福尼亚州, 洛杉矶
`zh-hant` / `zh-tw` / `zh-hk`	🇭🇰 繁體中文 (Traditional Chinese)	加利福尼亞州, 洛杉磯
`es`	🇪🇸 Español (Spanish)	California, Los Ángeles
`ja`	🇯🇵 日本語 (Japanese)	カリフォルニア州, ロサンゼルス
`ko`	🇰🇷 한국어 (Korean)	캘리포니아주, 로스앤젤레스
`de`	🇩🇪 Deutsch (German)	Kalifornien, Los Angeles
`fr`	🇫🇷 Français (French)	Californie, Los Angeles
`pt`	🇧🇷 Português (Portuguese)	Califórnia, Los Angeles
`it`	🇮🇹 Italiano (Italian)	California, Los Angeles
`nl`	🇳🇱 Nederlands (Dutch)	Californië, Los Angeles
`pl`	🇵🇱 Polski (Polish)	Kalifornia, Los Angeles
`ru`	🇷🇺 Русский (Russian)	Калифорния, Лос-Анджелес
`tr`	🇹🇷 Türkçe (Turkish)	Kaliforniya, Los Angeles
`vi`	🇻🇳 Tiếng Việt (Vietnamese)	California, Los Angeles
`id`	🇮🇩 Bahasa Indonesia (Indonesian)	California, Los Angeles

HTTP Status & Error Codes

OpenTax uses standard HTTP status codes to communicate request results. Error responses return structured JSON with an error message and code.

HTTP Status	Meaning	Description
200 OK	Success	The request succeeded and returned the requested tax data payload.
400 Bad Request	Invalid Parameters	Required parameters (e.g. 5-digit ZIP or query) are missing or malformed.
404 Not Found	Resource Not Found	The requested ZIP code or State does not exist in the database.
500 Server Error	Internal Error	An unexpected server error occurred during database lookup.

GET /api/v1/tax/lookup

ZIP Code Tax Lookup

Retrieves the comprehensive combined sales tax rate and jurisdiction breakdown (state, county, city, special tax district) for any 5-digit US ZIP postal code.

Query Parameters

Parameter	Type	Required	Description
`zip`	string	Required	5-digit US postal ZIP code. e.g. `90001`, `10001`.
`lang`	string	Optional	Response locale: `en`, `zh-hans`, `es`. Default: `en`.

Response Schema

Field	Type	Description
`zip`	string	5-digit postal code
`combined_rate`	float	Total combined tax rate (e.g. 0.0975 = 9.75%)
`state_rate`	float	Base statewide tax rate
`county_rate`	float	County-level tax rate
`city_rate`	float	Municipal city tax rate
`special_rate`	float	Special / District tax rate
`is_sst_member`	boolean	Whether state belongs to SST agreement

curl -X GET "https://opentaxus.com/api/v1/tax/lookup?zip=90001&lang=ru"

import requests

response = requests.get(
    "https://opentaxus.com/api/v1/tax/lookup",
    params={"zip": "90001", "lang": "ru"}
)
print(response.json())

const response = await fetch(
  "https://opentaxus.com/api/v1/tax/lookup?zip=90001&lang=ru"
);
const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://opentaxus.com/api/v1/tax/lookup?zip=90001&lang=ru")
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

200 OK application/json < 1ms

Try in Browser ↗

{
  "zip": "90001",
  "city_name": "Florence-Graham",
  "county_name": "Los Angeles County",
  "state_code": "ca",
  "state_name": "California",
  "combined_rate": 0.0975,
  "state_rate": 0.0725,
  "county_rate": 0.0000,
  "city_rate": 0.0000,
  "special_rate": 0.0250,
  "is_sst_member": false,
  "population": 62927
}

GET /api/v1/tax/calculate

Calculate Order Tax Amount

Computes the exact dollar sales tax amounts (state tax, county tax, city tax, special district tax) and the final grand total for an order purchase value in a specific ZIP code.

Query Parameters

Parameter	Type	Required	Description
`zip`	string	Required	5-digit destination postal ZIP code. e.g. `90001`.
`amount`	float	Required	Purchase subtotal dollar amount. e.g. `100.00`.
`lang`	string	Optional	Localization code: `en`, `zh-hans`, `es`.

Response Schema

Field	Type	Description
`amount`	float	Original order subtotal amount
`total_tax`	float	Total sales tax dollar amount
`total_amount`	float	Grand total payable (amount + total_tax)
`combined_rate`	float	Applicable combined sales tax rate
`state_tax` / `county_tax` / `city_tax` / `special_tax`	float	Tiered breakdown dollar amounts

curl -X GET "https://opentaxus.com/api/v1/tax/calculate?zip=90001&amount=100.00&lang=ru"

import requests

response = requests.get(
    "https://opentaxus.com/api/v1/tax/calculate",
    params={"zip": "90001", "amount": 100.00, "lang": "ru"}
)
print(response.json())

const response = await fetch(
  "https://opentaxus.com/api/v1/tax/calculate?zip=90001&amount=100.00&lang=ru"
);
const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://opentaxus.com/api/v1/tax/calculate?zip=90001&amount=100&lang=ru")
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

200 OK application/json < 1ms

Try in Browser ↗

{
  "amount": 100.00,
  "state_tax": 7.25,
  "county_tax": 0.00,
  "city_tax": 0.00,
  "special_tax": 2.50,
  "total_tax": 9.75,
  "total_amount": 109.75,
  "combined_rate": 0.0975
}

GET /api/v1/tax/search

Search & Autocomplete

High-speed in-memory prefix & fuzzy search for instant UI autocomplete dropdowns. Searches across ZIP codes, city names, counties, and states in English, Chinese, and Spanish.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Required	Search keyword (e.g. `900`, `Los Angeles`, `洛杉矶`).
`limit`	integer	Optional	Maximum results to return. Default: `10`.
`lang`	string	Optional	Target translation locale: `en`, `zh-hans`, `es`.

curl -X GET "https://opentaxus.com/api/v1/tax/search?q=90001&lang=ru&limit=5"

import requests

response = requests.get(
    "https://opentaxus.com/api/v1/tax/search",
    params={"q": "90001", "lang": "ru", "limit": 5}
)
print(response.json())

const response = await fetch(
  "https://opentaxus.com/api/v1/tax/search?q=90001&lang=ru&limit=5"
);
const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://opentaxus.com/api/v1/tax/search?q=90001&lang=ru")
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

200 OK application/json < 1ms

Try in Browser ↗

[
  {
    "zip": "90001",
    "city_name": "Florence-Graham",
    "state_code": "ca",
    "state_name": "California",
    "county_name": "Los Angeles County",
    "combined_rate": 0.0975,
    "url": "/zip/90001",
    "display_type": "zip"
  }
]

GET /api/v1/tax/nearest

Spatial Geo / Coordinates Lookup

Locates the nearest tax jurisdiction and sales tax rate given a latitude and longitude coordinate pair (Haversine spatial lookup). Perfect for mobile GPS and auto-geolocating customers.

Query Parameters

Parameter	Type	Required	Description
`lat`	float	Required	Latitude coordinate. e.g. `34.0522`.
`lng`	float	Required	Longitude coordinate. e.g. `-118.2437`.
`lang`	string	Optional	Locale code: `en`, `zh-hans`, `es`.

curl -X GET "https://opentaxus.com/api/v1/tax/nearest?lat=34.0522&lng=-118.2437&lang=ru"

import requests

response = requests.get(
    "https://opentaxus.com/api/v1/tax/nearest",
    params={"lat": 34.0522, "lng": -118.2437, "lang": "ru"}
)
print(response.json())

const response = await fetch(
  "https://opentaxus.com/api/v1/tax/nearest?lat=34.0522&lng=-118.2437&lang=ru"
);
const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://opentaxus.com/api/v1/tax/nearest?lat=34.05&lng=-118.24&lang=ru")
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

200 OK application/json < 1ms

Try in Browser ↗

{
  "zip": "90012",
  "city_name": "Los Angeles",
  "state_code": "ca",
  "combined_rate": 0.0950,
  "state_rate": 0.0725,
  "distance_km": 0.42
}

GET /api/v1/tax/state/{stateCode}

State Tax Rates Summary

Returns baseline sales tax parameters, SST membership status, minimum, maximum, and average combined rates, and total indexed cities for a given US State.

Path Parameters

Parameter	Type	Required	Description
`stateCode`	string	Required	2-letter US state abbreviation code. e.g. `ca`, `tx`, `ny`, `wa`.

curl -X GET "https://opentaxus.com/api/v1/tax/state/ca"

import requests

response = requests.get("https://opentaxus.com/api/v1/tax/state/ca")
print(response.json())

const response = await fetch("https://opentaxus.com/api/v1/tax/state/ca");
const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://opentaxus.com/api/v1/tax/state/ca")
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

200 OK application/json < 1ms

Try in Browser ↗

{
  "state_code": "ca",
  "state_name": {
    "en": "California",
    "es": "California",
    "zh-hans": "加利福尼亚州"
  },
  "state_rate": 0.0725,
  "min_rate": 0.0725,
  "max_rate": 0.1075,
  "avg_rate": 0.0885,
  "city_count": 1248,
  "is_sst_member": false
}

GET /api/v1/search-html

Instant Search Dropdown HTML

HTMX partial snippet endpoint that returns pre-rendered HTML search result items for real-time frontend search bars.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Required	Query string. e.g. `90001`, `Los Angeles`.
`lang`	string	Optional	Locale code: `en`, `zh-hans`, `es`.

curl -X GET "https://opentaxus.com/api/v1/search-html?q=90001&lang=ru"

200 OK text/html; charset=utf-8 < 1ms

<a href="/zip/90001" class="search-result-item">
  <div class="res-title">ZIP 90001</div>
  <div class="res-sub">Florence-Graham, California</div>
  <div class="res-rate">9.75%</div>
</a>

GET /healthz

Service Health & Liveness Check

Returns instantaneous health and uptime status of the HTTP server, SQLite database cache connection, and search index availability.

curl -X GET "https://opentaxus.com/healthz"

200 OK application/json < 1ms

Try in Browser ↗

{
  "status": "ok",
  "service": "open-tax",
  "time": "2026-08-31T17:30:00Z"
}

Client SDKs & Code Snippets

Integrate sales tax lookups directly into your e-commerce checkout flows, invoicing microservices, or ERP platforms.

⚡ JavaScript / TypeScript (Fetch API)

async function calculateOrderTax(zip, amount) {
  const url = `https://opentaxus.com/api/v1/tax/calculate?zip=${zip}&amount=${amount}`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Tax calculation failed: ${res.statusText}`);
  const { total_tax, combined_rate, total_amount } = await res.json();
  return { totalTax: total_tax, taxRate: combined_rate, grandTotal: total_amount };
}

🐍 Python (Requests)

import requests

def get_tax_rate(zip_code: str) -> float:
    url = "https://opentaxus.com/api/v1/tax/lookup"
    resp = requests.get(url, params={"zip": zip_code}, timeout=3)
    resp.raise_for_status()
    data = resp.json()
    return data.get("combined_rate", 0.0)

OpenTax REST API Reference

Authentication

Multi-Language Localization (i18n)

HTTP Status & Error Codes

ZIP Code Tax Lookup

Query Parameters

Response Schema

Calculate Order Tax Amount

Query Parameters

Response Schema

Search & Autocomplete

Query Parameters

Spatial Geo / Coordinates Lookup

Query Parameters

State Tax Rates Summary

Path Parameters

Instant Search Dropdown HTML

Query Parameters

Service Health & Liveness Check

Client SDKs & Code Snippets

Настройки файлов cookie