Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


TaxMan is a very early prototype of a universal tax calculator API. It's running at

What does it do?

It provides a JSON API to find out tax rates for countries around the world, and to perform the relevant calculations to work out what tax citizens pay (and have paid in the past).

Get a list of jurisdictions currently supported by TaxMan:

$ curl -s ''
  "message": "Welcome to the TaxMan",
  "jurisdictions": {
    "gb": ""

Get tax rates for the current year:

$ curl -s ''
  "data": {
    "allowances": {
      "personal": 8105,
      "personal_income_limit": 25400
    "income_tax": {
      "bands": [
          "width": 34370,
          "rate": 0.2

Get the UK personal allowance for 2002:

$ curl -s '' | json data.allowances.personal

Find out how much income tax you would pay with a salary of £22,000:

$ curl -s '' | json

And so on. Specify a callback GET parameter if you want JSONP back rather than JSON.

How can I make it better?

You can add a tax calculator for your own jurisdiction! Fork this repository and add a module for your jurisdiction, using the ISO 3166 two-letter code for your country as a name. For example, if you wanted to add taxes for Spain, you'd create tax/es/, implementing the calculate() function:

exports.calculate = (params) ->
  # do your tax calculation...

  return {
    options: [parsed options]
    data: [raw data used to perform the tax calculation]
    calculation: [the tax calculation]

At the moment we place no restrictions on what you return from the calculate function. That said, it is hoped that as we add more jurisdictions we will work out which parts of the API we can standardise. Consistency across jurisdictions is very important if TaxMan is to be useful, and at the moment we are relying entirely on contributors' discipline to ensure it.

Developer details

To develop, you'll need to have Node.js and npm installed.

Getting started

$ npm install .

Development workflow

$ grunt

Code styles are checked by CoffeeLint and tests runs by Mocha automatically whenever watched files are changed. These tasks helps you while developing.

Running the server locally

$ grunt server

By watch process, the server automatically restarts whenever you change CoffeeScript files.

Running tests

$ grunt test

All tests in tax/*/test/*.coffee run. It is expected that you write tests with Mocha and should.js.


A very early prototype of a universal tax calculator API






No releases published


No packages published