OpenTax REST API Reference
La API REST de OpenTax proporciona consultas de tasas de impuestos sobre ventas en menos de un milisegundo, cálculos de desglose de múltiples jurisdicciones, búsquedas espaciales por GPS y búsqueda predictiva en los 50 estados de EE. UU., más de 41,000 códigos ZIP y regiones de cumplimiento SST.
https://opentaxus.com/api/v1
Autenticación
Los endpoints públicos de OpenTax son de uso libre sin necesidad de una clave API. Para integraciones empresariales o exenciones de límites, incluya su token en el encabezado Authorization:
Authorization: Bearer YOUR_API_KEY
Localización Multilingüe (i18n)
Todos los endpoints aceptan un parámetro de consulta opcional lang para devolver nombres de estados, condados y ciudades traducidos.
| 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 |
Códigos de Estado y Errores
OpenTax utiliza códigos de estado HTTP estándar. Las respuestas de error devuelven JSON estructurado con un mensaje explicativo.
| 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. |
/api/v1/tax/lookup
Consulta de Impuesto por Código ZIP
Recupera la tasa de impuesto sobre las ventas combinada completa y el desglose de la jurisdicción (estado, condado, ciudad, distrito fiscal especial) para cualquier código postal ZIP de 5 dígitos de EE. UU.
Parámetros de Consulta
| 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. |
Esquema de Respuesta
| 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=es"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/lookup",
params={"zip": "90001", "lang": "es"}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/lookup?zip=90001&lang=es"
);
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=es")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}{
"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
}/api/v1/tax/calculate
Calcular Impuesto de Pedido
Calcula los montos exactos en dólares del impuesto sobre las ventas y el total general final para el valor de compra de un pedido en un código ZIP específico.
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=es"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/calculate",
params={"zip": "90001", "amount": 100.00, "lang": "es"}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/calculate?zip=90001&amount=100.00&lang=es"
);
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=es")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}{
"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
}/api/v1/tax/search
Búsqueda y Autocompletar
Búsqueda de prefijo y difusa de alta velocidad para menús desplegables de autocompletado en la interfaz de usuario en inglés, chino y español.
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=es&limit=5"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/search",
params={"q": "90001", "lang": "es", "limit": 5}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/search?q=90001&lang=es&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=es")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}[
{
"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"
}
]/api/v1/tax/nearest
Búsqueda Espacial por Coordenadas
Localiza la jurisdicción fiscal y la tasa más cercanas dadas unas coordenadas de latitud y longitud.
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=es"import requests
response = requests.get(
"https://opentaxus.com/api/v1/tax/nearest",
params={"lat": 34.0522, "lng": -118.2437, "lang": "es"}
)
print(response.json())const response = await fetch(
"https://opentaxus.com/api/v1/tax/nearest?lat=34.0522&lng=-118.2437&lang=es"
);
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=es")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}{
"zip": "90012",
"city_name": "Los Angeles",
"state_code": "ca",
"combined_rate": 0.0950,
"state_rate": 0.0725,
"distance_km": 0.42
}/api/v1/tax/state/{stateCode}
Resumen de Impuestos Estatales
Devuelve los parámetros básicos del impuesto sobre las ventas, membresía SST, tasas mínimas, máximas y promedio para un estado de EE. UU.
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))
}{
"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
}/api/v1/search-html
HTML de Menú Desplegable HTMX
Endpoint de fragmento HTMX que devuelve elementos de resultados de búsqueda HTML pre-renderizados para barras de búsqueda frontend.
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=es"<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>/healthz
Estado de Salud y Disponibilidad
Devuelve el estado instantáneo de salud y tiempo de actividad del servidor HTTP y la conexión SQLite.
curl -X GET "https://opentaxus.com/healthz"{
"status": "ok",
"service": "open-tax",
"time": "2026-08-31T17:30:00Z"
}SDKs y Fragmentos de Código
Integre búsquedas de impuestos sobre ventas directamente en sus flujos de pago de comercio electrónico o plataformas ERP.
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 };
}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)