Tax Rate API

Overview

The Tax Rate API provides global tax rate information including VAT, GST, sales tax, corporate tax, and other tax types for countries worldwide. Data is automatically synchronized from authoritative sources on a regular basis.

Note: This API provides read-only access to tax rate data. Data synchronization is managed internally by scheduled tasks.

Base Endpoint: /api/bigdata/taxrate

API Endpoints

1. List All Tax Rates (Paginated)

Retrieve a paginated list of all tax rate records.

Endpoint: GET /api/bigdata/taxrate/list

Parameters:

Parameter	Type	Required	Description
page	Integer	No	Page number, starting from 0 (default: 0)
size	Integer	No	Page size (default: 20)

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/list?page=0&size=20" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response:

json

{
  "code": 200,
  "msg": "Request successful",
  "data": {
    "content": [
      {
        "countryCode": "DE",
        "countryName": "Germany",
        "taxType": "VAT",
        "taxNameLocal": "Umsatzsteuer",
        "taxNameEn": "Value Added Tax",
        "taxAbbr": "MwSt.",
        "rateLevel": "standard",
        "rateLevelName": "Standard rate",
        "rateValue": 19.00,
        "currencyCode": "EUR",
        "euMember": true,
        "oecdMember": true,
        "effectiveFrom": "2023-01-01T00:00:00",
        "effectiveTo": null,
        "dataSource": "EU_VAT",
        "lastSyncTime": "2026-05-21T02:00:00"
      }
    ],
    "totalElements": 1500,
    "totalPages": 75,
    "number": 0,
    "size": 20
  }
}

2. Get Rates by Country

Query all current effective tax rates for a specific country.

Endpoint: GET /api/bigdata/taxrate/country/{countryCode}

Parameters:

Parameter	Type	Required	Description
countryCode	String	Yes	ISO 3166-1 alpha-2 country code (e.g., US, DE, FR)

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/country/DE" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response:

json

{
  "code": 200,
  "msg": "Request successful",
  "data": [
    {
      "countryCode": "DE",
      "countryName": "Germany",
      "taxType": "VAT",
      "taxNameLocal": "Umsatzsteuer",
      "taxAbbr": "MwSt.",
      "rateLevel": "standard",
      "rateValue": 19.00,
      "currencyCode": "EUR",
      "euMember": true
    },
    {
      "countryCode": "DE",
      "countryName": "Germany",
      "taxType": "VAT",
      "rateLevel": "reduced",
      "rateValue": 7.00,
      "currencyCode": "EUR",
      "applicableScope": "Food, books, medical supplies"
    }
  ]
}

3. Get Rates by Country and Region

Query tax rates for a specific country and region.

Endpoint: GET /api/bigdata/taxrate/country/{countryCode}/region/{regionCode}

Parameters:

Parameter	Type	Required	Description
countryCode	String	Yes	ISO 3166-1 alpha-2 country code
regionCode	String	Yes	ISO 3166-2 region/state code

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/country/US/region/CA" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

4. Get Rates by Country and Tax Type

Query specific tax type rates for a country.

Endpoint: GET /api/bigdata/taxrate/country/{countryCode}/type/{taxType}

Parameters:

Parameter	Type	Required	Description
countryCode	String	Yes	ISO 3166-1 alpha-2 country code
taxType	String	Yes	Tax type code (VAT, GST, SalesTax, etc.)

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/country/GB/type/VAT" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

5. Get Standard VAT Rate

Query the standard VAT rate for a specific country.

Endpoint: GET /api/bigdata/taxrate/country/{countryCode}/standard

Parameters:

Parameter	Type	Required	Description
countryCode	String	Yes	ISO 3166-1 alpha-2 country code

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/country/FR/standard" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response:

json

{
  "code": 200,
  "msg": "Request successful",
  "data": {
    "countryCode": "FR",
    "countryName": "France",
    "taxType": "VAT",
    "rateLevel": "standard",
    "rateValue": 20.00,
    "currencyCode": "EUR",
    "euMember": true
  }
}

6. Get All EU VAT Rates

Query VAT rates for all European Union member countries.

Endpoint: GET /api/bigdata/taxrate/eu/all

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/eu/all" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

7. Get OECD Rates by Tax Type

Query tax rates for all OECD member countries by tax type.

Endpoint: GET /api/bigdata/taxrate/oecd/{taxType}

Parameters:

Parameter	Type	Required	Description
taxType	String	Yes	Tax type code (VAT, GST, CorporateTax, etc.)

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/oecd/VAT" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

8. Get Rates by Tax Number

Query tax rates associated with a specific tax number.

Endpoint: GET /api/bigdata/taxrate/taxnumber/{taxNumber}

Parameters:

Parameter	Type	Required	Description
taxNumber	String	Yes	Tax identification number

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/taxnumber/DE123456789" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

9. Get All Tax Types

Retrieve a list of all supported tax type codes.

Endpoint: GET /api/bigdata/taxrate/types

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/types" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response:

json

{
  "code": 200,
  "msg": "Request successful",
  "data": ["VAT", "GST", "SalesTax", "ConsumptionTax", "CorporateTax", "IncomeTax", "ExciseTax", "PropertyTax", "CustomsDuty"]
}

10. Get All Rate Levels

Retrieve a list of all supported tax rate levels.

Endpoint: GET /api/bigdata/taxrate/levels

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/levels" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response:

json

{
  "code": 200,
  "msg": "Request successful",
  "data": ["standard", "reduced", "reduced1", "reduced2", "super_reduced", "parking", "zero", "exempt"]
}

11. Get Tax Rate by ID

Retrieve a single tax rate record by its ID.

Endpoint: GET /api/bigdata/taxrate/{id}

Parameters:

Parameter	Type	Required	Description
id	Long	Yes	Tax rate record ID

Request:

bash

curl "https://api.alaikis.com/std/api/bigdata/taxrate/1" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Data Model

TaxRate Fields

Field	Type	Description
id	Long	Record ID
countryCode	String	ISO 3166-1 alpha-2 country code
regionCode	String	ISO 3166-2 region/state code
countryName	String	Country name
regionName	String	Region/state name
taxType	String	Tax type code
taxNameLocal	String	Local tax name
taxNameEn	String	English tax name
taxAbbr	String	Tax abbreviation
rateLevel	String	Rate level
rateLevelName	String	Rate level description
rateValue	BigDecimal	Tax rate percentage value
effectiveFrom	DateTime	Effective start date
effectiveTo	DateTime	Effective end date (null means currently active)
currencyCode	String	ISO 4217 currency code
euMember	Boolean	EU member state
oecdMember	Boolean	OECD member state
taxIdFormat	String	Tax ID format description
taxIdPattern	String	Tax ID regex pattern
filingFrequency	String	Filing frequency
applicableScope	String	Applicable scope
excludedScope	String	Excluded scope
dataSource	String	Data source identifier
sourceUrl	String	Data source URL
versionDate	DateTime	Data version date
lastSyncTime	DateTime	Last sync time
enabled	Boolean	Whether enabled

Tax Types Reference

Code	Description
VAT	Value Added Tax
GST	Goods and Services Tax
SalesTax	Sales Tax
ConsumptionTax	Consumption Tax
CorporateTax	Corporate Income Tax
IncomeTax	Personal Income Tax
ExciseTax	Excise Tax
PropertyTax	Property Tax
CustomsDuty	Customs Duty

Rate Levels Reference

Level	Description
standard	Standard rate
reduced	Reduced rate
reduced1	First reduced rate
reduced2	Second reduced rate
super_reduced	Super reduced rate
parking	Parking rate (transitional)
zero	Zero rate
exempt	Exempt

Data Sources

Source	Description
EU_VAT	European Union official VAT rates
OECD	OECD tax data
WIKIPEDIA	Wikipedia tax rate data
CUSTOM	Custom data

Data Update Frequency

Tax rate data is automatically synchronized on a regular basis:

EU VAT rates: Daily sync
OECD data: Monthly sync
Wikipedia data: Monthly sync
China tax rates: Monthly sync

You can check the sync task status via the Scheduler Status API.

Tax Rate API ​

Overview ​

API Endpoints ​

1. List All Tax Rates (Paginated) ​

2. Get Rates by Country ​

3. Get Rates by Country and Region ​

4. Get Rates by Country and Tax Type ​

5. Get Standard VAT Rate ​

6. Get All EU VAT Rates ​

7. Get OECD Rates by Tax Type ​

8. Get Rates by Tax Number ​

9. Get All Tax Types ​

10. Get All Rate Levels ​

11. Get Tax Rate by ID ​

Data Model ​

TaxRate Fields ​

Tax Types Reference ​

Rate Levels Reference ​

Data Sources ​

Data Update Frequency ​

Tax Rate API

Overview

API Endpoints

1. List All Tax Rates (Paginated)

2. Get Rates by Country

3. Get Rates by Country and Region

4. Get Rates by Country and Tax Type

5. Get Standard VAT Rate

6. Get All EU VAT Rates

7. Get OECD Rates by Tax Type

8. Get Rates by Tax Number

9. Get All Tax Types

10. Get All Rate Levels

11. Get Tax Rate by ID

Data Model

TaxRate Fields

Tax Types Reference

Rate Levels Reference

Data Sources

Data Update Frequency