OpenTax REST API Reference
OpenTax 提供全美 50 州、41,000+ 邮政编码的高性能、亚毫秒级综合消费税率查询与拆分计算接口。支持州税、县税、市税、特别区税多级明细拆分、SST 联盟合规规则、GPS 经纬度空间定位查询以及中英西多语言支持。
接口请求基准 URL (Base URL)
HTTP/1.1 & HTTP/2
HTTPS
https://opentaxus.com/api/v1
认证与鉴权 (Authentication)
OpenTax 基础查询接口支持公开免费调用，无需 API Key。企业级专用接入、高并发定制配额或专用 SLA 实例，可在 HTTP 请求头中附带 Authorization 密钥：
Authorization: Bearer YOUR_API_KEY
多语言本地化支持 (Localization / i18n)
所有接口均支持传入可选的 lang 查询参数，用于返回对应语言的州、县、城市名称。
| 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 状态码与错误处理
OpenTax 遵循标准 HTTP 状态码规范。发生错误时将返回结构化 JSON 错误响应。
| HTTP Status | Meaning | Description |
|---|---|---|
| 200 OK | Success | 请求成功并返回税率数据负载。 |
| 400 Bad Request | Invalid Parameters | 请求参数不合规（如缺少必填的 5 位邮政编码或金额）。 |
| 404 Not Found | Resource Not Found | 未查询到对应的邮编或州记录。 |
| 500 Server Error | Internal Error | 服务端内部查询故障。 |
GET
/api/v1/tax/lookup
ZIP 邮编综合税率查询
根据 5 位美国邮政编码（ZIP Code），获取该地区的最高综合消费税率与层级明细拆分（州基准税率、县税率、市税率、特别区税率）及 SST 成员合规状态。
请求参数 (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 位邮政编码 |
combined_rate |
float | 总综合税率（如 0.0975 代表 9.75%） |
state_rate |
float | 州级基准消费税率 |
county_rate |
float | 县级消费税率 |
city_rate |
float | 市镇级消费税率 |
special_rate |
float | 特别税区 / 附加税率 |
is_sst_member |
boolean | 是否属于 SST 简化税制协定成员州 |
curl -X GET "https://opentaxus.com/api/v1/tax/lookup?zip=90001&lang=zh-hans"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/lookup",
params={"zip": "90001", "lang": "zh-hans"}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/lookup?zip=90001&lang=zh-hans"
);
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=zh-hans")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
200 OK
application/json
< 1ms
在浏览器打开 ↗
{
"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
订单消费税额精确计算
根据目的地邮政编码与交易金额，即时计算出分级税费（州税额、县税额、市税额、特别区税额）、总税额以及订单最终应付金额。
请求参数 (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 | 原始订单商品小计金额 |
total_tax |
float | 应缴消费税总额 |
total_amount |
float | 含税订单最终应付总额 (amount + total_tax) |
combined_rate |
float | 适用综合税率 |
state_tax / county_tax / city_tax / special_tax |
float | 各层级管辖区细分税额 |
curl -X GET "https://opentaxus.com/api/v1/tax/calculate?zip=90001&amount=100.00&lang=zh-hans"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/calculate",
params={"zip": "90001", "amount": 100.00, "lang": "zh-hans"}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/calculate?zip=90001&amount=100.00&lang=zh-hans"
);
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=zh-hans")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
200 OK
application/json
< 1ms
在浏览器打开 ↗
{
"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
地理与邮编搜索补全
高性能内存 Trie 树搜索，支持按邮编前缀、城市英文/中文名称、县名、州缩写进行毫秒级模糊匹配与联想补全。
请求参数 (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=zh-hans&limit=5"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/search",
params={"q": "90001", "lang": "zh-hans", "limit": 5}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/search?q=90001&lang=zh-hans&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=zh-hans")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
200 OK
application/json
< 1ms
在浏览器打开 ↗
[
{
"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
GPS 经纬度空间定位查询
根据经度（lng）与纬度（lat）坐标，通过球面大圆距离算法（Haversine）自动匹配物理距离最近的税收管辖区及适用消费税率。适用于移动设备自动定位免填邮编结账场景。
请求参数 (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=zh-hans"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/nearest",
params={"lat": 34.0522, "lng": -118.2437, "lang": "zh-hans"}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/nearest?lat=34.0522&lng=-118.2437&lang=zh-hans"
);
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=zh-hans")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
200 OK
application/json
< 1ms
在浏览器打开 ↗
{
"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}
全州消费税概览与统计
查询特定州的基准税率、最高综合税率、最低综合税率、平均税率、收录城市总数以及 SST 成员认证。
路径参数 (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
在浏览器打开 ↗
{
"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
实时搜索下拉 HTML 片段
HTMX 服务端渲染片段接口，直接返回预渲染的 HTML 搜索结果项，无需前端编写模板即可实现即时下拉交互。
请求参数 (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=zh-hans"
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
服务健康与存活探针
用于 Kubernetes / Docker 容器存活探针（Liveness & Readiness Probe）及监控服务健康状态。
curl -X GET "https://opentaxus.com/healthz"
200 OK
application/json
< 1ms
在浏览器打开 ↗
{
"status": "ok",
"service": "open-tax",
"time": "2026-08-31T17:30:00Z"
}客户端接入示例 (SDKs & Code Snippets)
快速将消费税查询与计算功能集成至您的电商结算系统、SaaS 开票平台或 ERP 系统。
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)