UAE HS Codes API
Look up UAE Customs Harmonized System (HS) codes, search bilingual (English & Arabic) descriptions, and calculate import duties & landed costs — all in one API.
curl https://www.uaehscodes.com/api/v1/health
{
"success": true,
"data": {
"status": "ok",
"api_version": "1.0.0"
}
}
Base URL
https://www.uaehscodes.com/api/v1
All responses are JSON (Content-Type: application/json). All endpoints use GET.
Machine-readable contract: openapi.yaml. RapidAPI packaging descriptor is available in project root as rapidapi.json.
Authentication
Pass your API key in the X-Api-Key request header:
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://www.uaehscodes.com/api/v1/search?q=machinery"
The /api/v1/health endpoint is open (no key required).
All other endpoints require a valid key.
Rate Limiting
| Tier | Requests / Minute | Requests / Day |
|---|---|---|
| Free | 30 | 1,000 |
| Basic | 60 | 5,000 |
| Pro | 200 | 50,000 |
Rate limit headers are included in every response:
X-RateLimit-Limit-Minute,
X-RateLimit-Remaining-Minute,
X-RateLimit-Limit-Day,
X-RateLimit-Remaining-Day.
Endpoints
/api/v1/health
No auth required
Health check — verify the API is online.
Example response{
"success": true,
"data": {
"service": "uae-hs-codes-public-api",
"status": "ok",
"foundation_schema_ready": true
},
"meta": {
"timestamp": "2026-05-04T12:00:00+00:00",
"api_version": "1.0.0"
}
}
/api/v1/hs-codes/{hs_code}
Look up a single HS code by its numeric code (2–14 digits).
| Param | Type | Required | Description |
|---|---|---|---|
hs_code | string | ✅ Path | HS code digits, e.g. 852321000000 |
GET /api/v1/hs-codes/852321000000
X-Api-Key: YOUR_API_KEY
{
"success": true,
"data": {
"hs_code": "852321000000",
"description": {
"en": "Magnetic media cards incorporating a magnetic stripe",
"ar": "..."
},
"level": 12,
"parent_id": null,
"tariff_rate": 5,
"is_active": true
},
"meta": {
"timestamp": "2026-05-04T12:00:00+00:00",
"api_version": "1.0.0"
}
}
/api/v1/search
Search HS codes by keyword across English and Arabic descriptions.
| Param | Type | Required | Description |
|---|---|---|---|
q | string | ✅ | Search term, min 2 chars |
level | integer | — | Filter by code length: 2, 4, 6, 8, 10, or 12 |
limit | integer | — | Results per page, 1–50 (default 20) |
offset | integer | — | Pagination offset (default 0) |
GET /api/v1/search?q=magnetic&limit=3
X-Api-Key: YOUR_API_KEY
{
"success": true,
"data": [
{
"hs_code": "260111000003",
"description": {
"en": "Magnetite Ores...",
"ar": "..."
},
"tariff_rate": 5
}
],
"meta": {
"total": 33,
"limit": 3,
"offset": 0,
"count": 1,
"timestamp": "2026-05-04T12:00:00+00:00",
"api_version": "1.0.0"
}
}
/api/v1/hs-codes/{hs_code}/children
Return one level down of child codes for a given parent code.
| Param | Type | Required | Description |
|---|---|---|---|
hs_code | string | ✅ Path | Parent HS code (2–12 digits) |
limit | integer | — | 1–50 (default 50) |
offset | integer | — | Pagination offset (default 0) |
/api/v1/tariff/calculate
Calculate import duty and optional UAE VAT for a declared shipment value.
| Param | Type | Required | Description |
|---|---|---|---|
hs_code | string | ✅ | HS code (2–14 digits) |
value | number | ✅ | Declared goods value (CIF basis) |
currency | string | — | Currency label, default USD (no conversion applied) |
include_vat | boolean | — | 1 or true to include UAE 5% VAT |
GET /api/v1/tariff/calculate?hs_code=852321000000&value=1000¤cy=USD&include_vat=1
X-Api-Key: YOUR_API_KEY
{
"success": true,
"data": {
"hs_code": "852321000000",
"product": "Magnetic media cards incorporating a magnetic stripe",
"calculation": {
"declared_value": 1000,
"currency": "USD",
"import_duty_rate": 5,
"import_duty_amount": 50,
"vat_rate": 5,
"vat_amount": 52.5,
"total_duties_taxes": 102.5,
"landed_cost": 1102.5
},
"notes": "Rates are indicative. Verify with UAE customs authority for official assessment."
},
"meta": {
"timestamp": "2026-05-04T12:00:00+00:00",
"api_version": "1.0.0"
}
}
Error Codes
| error.code | HTTP Status | Description |
|---|---|---|
missing_api_key | 401 | No API key provided in the header |
invalid_api_key | 401 | Key not found or inactive |
api_key_expired | 401 | Key has passed its expiry date |
rate_limit_exceeded | 429 | Too many requests; check Retry-After header |
invalid_code | 400 | HS code format invalid |
invalid_value | 400 | Value parameter missing or out of range |
query_too_short | 400 | Search query must be ≥ 2 characters |
not_found | 404 | HS code not found in the database |
db_unavailable | 503 | Database temporarily unavailable |
Code Examples
# HS Code Lookup
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://www.uaehscodes.com/api/v1/hs-codes/852321000000"
# Search
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://www.uaehscodes.com/api/v1/search?q=magnetic&limit=5"
# Tariff Calculator (with VAT)
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://www.uaehscodes.com/api/v1/tariff/calculate?hs_code=852321000000&value=1000¤cy=USD&include_vat=1"
import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://www.uaehscodes.com/api/v1"
headers = {"X-Api-Key": API_KEY}
# Lookup
r = requests.get(f"{BASE}/hs-codes/852321000000", headers=headers)
print(r.json())
# Search
r = requests.get(f"{BASE}/search", headers=headers, params={"q": "magnetic", "limit": 5})
data = r.json()
for item in data["data"]:
print(item["hs_code"], item["description"]["en"])
# Tariff
r = requests.get(f"{BASE}/tariff/calculate", headers=headers,
params={"hs_code": "852321000000", "value": 1000, "currency": "USD", "include_vat": 1})
calc = r.json()["data"]["calculation"]
print(f"Landed cost: {calc['landed_cost']} {calc['currency']}")
const API_KEY = "YOUR_API_KEY";
const BASE = "https://www.uaehscodes.com/api/v1";
const headers = { "X-Api-Key": API_KEY };
// Lookup
const lookup = await fetch(`${BASE}/hs-codes/852321000000`, { headers });
const { data } = await lookup.json();
console.log(data.description.en);
// Search
const search = await fetch(`${BASE}/search?q=magnetic&limit=5`, { headers });
const results = await search.json();
results.data.forEach(item => console.log(item.hs_code, item.description.en));
// Tariff
const tariff = await fetch(
`${BASE}/tariff/calculate?hs_code=852321000000&value=1000&include_vat=1`,
{ headers }
);
const { calculation } = (await tariff.json()).data;
console.log("Landed cost:", calculation.landed_cost, calculation.currency);
<?php
$apiKey = "YOUR_API_KEY";
$base = "https://www.uaehscodes.com/api/v1";
function hsApiGet(string $path, array $params = [], string $key = ""): array {
$url = $base . $path . ($params ? "?" . http_build_query($params) : "");
$ctx = stream_context_create(["http" => [
"method" => "GET",
"header" => "X-Api-Key: $key\r\n",
]]);
return json_decode(file_get_contents($url, false, $ctx), true);
}
// Lookup
$data = hsApiGet("/hs-codes/852321000000", [], $apiKey);
echo $data["data"]["description"]["en"] . PHP_EOL;
// Search
$results = hsApiGet("/search", ["q" => "magnetic", "limit" => 5], $apiKey);
foreach ($results["data"] as $item) {
echo $item["hs_code"] . " – " . $item["description"]["en"] . PHP_EOL;
}
// Tariff
$calc = hsApiGet("/tariff/calculate", [
"hs_code" => "852321000000",
"value" => 1000,
"currency" => "USD",
"include_vat" => 1,
], $apiKey);
echo "Landed cost: " . $calc["data"]["calculation"]["landed_cost"] . PHP_EOL;