HS Code Intelligence Platform
UAE Trade Workflows
REST API · v1.0

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.

Free tier: 30 requests/minute · 1,000 requests/day. To request a key, contact us at api@uaehscodes.com.

Rate Limiting

TierRequests / MinuteRequests / Day
Free301,000
Basic605,000
Pro20050,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

GET /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"
    }
}
GET /api/v1/hs-codes/{hs_code}

Look up a single HS code by its numeric code (2–14 digits).

ParamTypeRequiredDescription
hs_codestring✅ PathHS code digits, e.g. 852321000000
Example
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"
    }
}
GET /api/v1/search

Search HS codes by keyword across English and Arabic descriptions.

ParamTypeRequiredDescription
qstringSearch term, min 2 chars
levelintegerFilter by code length: 2, 4, 6, 8, 10, or 12
limitintegerResults per page, 1–50 (default 20)
offsetintegerPagination offset (default 0)
Example
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"
    }
}
GET /api/v1/hs-codes/{hs_code}/children

Return one level down of child codes for a given parent code.

ParamTypeRequiredDescription
hs_codestring✅ PathParent HS code (2–12 digits)
limitinteger1–50 (default 50)
offsetintegerPagination offset (default 0)
GET /api/v1/tariff/calculate

Calculate import duty and optional UAE VAT for a declared shipment value.

ParamTypeRequiredDescription
hs_codestringHS code (2–14 digits)
valuenumberDeclared goods value (CIF basis)
currencystringCurrency label, default USD (no conversion applied)
include_vatboolean1 or true to include UAE 5% VAT
Example
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.codeHTTP StatusDescription
missing_api_key401No API key provided in the header
invalid_api_key401Key not found or inactive
api_key_expired401Key has passed its expiry date
rate_limit_exceeded429Too many requests; check Retry-After header
invalid_code400HS code format invalid
invalid_value400Value parameter missing or out of range
query_too_short400Search query must be ≥ 2 characters
not_found404HS code not found in the database
db_unavailable503Database 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;