Developer Documentation

Access & request limits

Anonymous requests are rate limited by IP address. If you have an account then your account type determines your request limits.

Your API token is available on your account page. Use the token in the authorization header to allot the request to your account:

$ curl https://taxtools.io/api/188.226.197.55 \
  -H 'authorization: token xxxxxxxx-xxxx'

The request limits are included in the headers of all API requests:

$ curl https://taxtools.io/api/188.226.197.55 \
  -H 'authorization: token xxxxxxxx-xxxx' \
  -I -X GET # headers only
HTTP/1.1 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1490107762
Content-Type: application/json; charset=utf-8

The X-RateLimit-Reset is a rolling window, and shown in unix seconds. Once the limits are exceeded a 429 Too many requests is returned.

CORS

All API endpoints support CORS by default.

API endpoints

How to…

Calculate inclusive VAT

How to work out amount of inclusive VAT on a given price (example):

const cost = 1099; // in cents/pennies
const rate = 24; // based on DK VAT rate
const vat = Math.round(cost / (1 + rate / 100));

Calculate VAT

How to work out the additional VAT (example):

const cost = 1099;
const rate = 20; // based on GB VAT rate

// note: to display, show `vat.toFixed(2)`
const vat = cost * (1 + rate / 100) - cost;

Authenticate requests

Ideal for server side request, you can pass your secret token instead of generating a bearer token:

$ curl https://taxtools.io/api/188.226.197.55 \
  -H 'authorization: token xxxxxxxx-xxxx'

Generate a bearer token

On the server, provide the client side code with a token

const jwt = require('jsonwebtoken');
const accountId = 'AC000000';
const secret = 'xxxxxxxx-xxxx';

// token can be used in the browser for up to 1 hour
const token = jwt.sign({ id: accountId }, secret, { expiresIn: '1 hour' });

Now in the client, include an authorization: Bearer ${token} header in all API requests:

const xhr = new XMLHttpRequest();
xhr.onload = function() {
  console.log(JSON.parse(xhr.responseText));
};

// window.token is passed through via your server
xhr.setRequestHeader('authorization', `Bearer ${window.token}`);
xhr.open('GET', 'https://taxtools.io/api');
xhr.send();

Check current request limits

Use the /api/account endpoint. This does not count against your request limit and can be used to check the current state of requests remaining:

$ curl https://taxtools.io/api/account \
  -H 'authorization: token xxxxxxxx-xxxx'

Further help

If you have a question beyond the scope of this web site's documentation, please get in touch directly with your question.