VAT Rate Lookup API

Overview

The VAT Rate Lookup API provides a machine-consumable service allowing for the easy lookup of current and historic VAT rates for all EU countries. The service is a RESTful API generating a JSON output.

Quickstart / Current Rates

The API can be accessed via a GET request to http://api.vatlookup.eu/rates/ or via SSL to https://api.vatlookup.eu/rates/. In its most basic form the API will return current VAT rates (ie. those in force at the time the request is made).

Country Codes

In order to obtain meaningful data a country name or code must be specified. The API currently supports both ISO 3166-1 Alpha-2 codes and English short names (ie. common names in English). A full list of available codes, in JSON format, can be generated from the API itself by issuing a GET request to http://api.vatlookup.eu/countrylist/.

Current Rates

A request for the current Belgian VAT rates is made as follows:

GET http://api.vatlookup.eu/rates/be/

The response to this request is (see response documentation below):

{"rates":[{"name":"Super Reduced","rates":[]},{"name":"Reduced","rates":["6","12"]},{"name":"Standard","rates":["21"]},{"name":"Increased","rates":[]},{"name":"Parking","rates":["12"]}],"disclaimer":"Rates data is based on information published by the European Commission, updated 1st January 2015."}

Historic Data

The API can return VAT rates for a given point in time by supplying a date in the request. The date must be in the standard Internet date format YYYY-MM-DD (ISO 8601).

GET http://api.vatlookup.eu/rates/be/2014-12-10

If no data exists for the given country and date an error element will be returned stating “No rates found”.

Response Data

Valid Response

The API response, for all requests made to the API, is an HTTP 200 code with a body of JSON formatted array with textual indexes as follows:

  • rates — numerically indexed array containing details of each of the recognised VAT rates. Each element itself contains a descriptively indexed array:
    • name — VAT type name (“Super Reduced”, “Reduced”, “Standard”, “Increased” or “Parking”).
    • rates — numerically indexed array of currently applicable percentage rates as floating point numbers. (NB. At any one time a country may apply more than one value for each rate depending on the goods or services being supplied.)
  • disclaimer — a standard disclaimer.

The following in an abbreviated, formatted typical response in JSON format:

{
   "rates":[
      ...
      {
         "name":"Reduced",
         "rates":[
            "6",
            "12"
         ]
      },
      ...
   ],
   "disclaimer":"Rates data is based on information published by the European Commission, updated 1st January 2015."
}

The same JSON response parsed as a PHP array:

array(2) {
  ["rates"]=>
  array(5) {
    ...
    [1]=>
    array(2) {
      ["name"]=>
      string(7) "Reduced"
      ["rates"]=>
      array(2) {
        [0]=>
        float(6)
        [1]=>
        float(12)
      }
    }
    ...
  }
  ["disclaimer"]=>
  string(98) "Rates data is based on information published by the European Commission, updated 1st January 2015."
}

Error Response

On error the API with return a JSON formatted array with a single “error” element. The element contains a text description of the error. The HTTP response code for most operationally generated errors is 404, internal server errors generate an HTTP 500 response.

{
   "error":"Country not found"
}