avalara-taxrates

Avalara TaxRates API client for node.js

This is a simple library to make it easier to interface with the Avalara TaxRates REST API. TaxRates will provide the overall rate and a breakdown of the rate's components for a U.S. or Canadian street address or zip/postal code.

You must register for a unique key to use this API. The TaxRates API is separate from other Avalara APIs and has its own registration. Please see our authentication documentation for a current link to the Tax Rates API registration.

Methods

The library has two methods.

To ensure the definitions of API variables are consistent across multiple libraries, we keep a master reference of what API variables mean/represent. The phrase "see definitions" below is linked to it, though most should be self-explanatory.

• getTaxByAddress(APIKey, street, city, state, country, postal, callback)

  • APIKey: Your assigned API Key (just the key, no other text)
  • street: see definitions (optional)
  • state: see definitions
  • country: see definitions
  • postal: see definitions (optional)
  • callback: a callback function to handle the return value

• getTaxByZip(APIKey, country, postal, callback)

  • APIKey: Your assigned API Key (just the key, no other text)
  • country: see definitions
  • postal: see definitions
  • callback: a callback function to handle the return value

For optional arguments, you may leave empty, but include the comma, e.g.: getTaxByAddress(APIKey, street, , state, country, , callback);

Validation

The library gently validates the required data elements in both methods and will throw an exception with an error message if it detects a non-conforming element.

When throwing the exception, it will also print debug information about the method arguments to the console.

Return Values

Each will return a JavaScript object.

If the call fails and there has been a 4xx status code returned by the server, object.error will be true and the object will have the following properties:

• object.code - the 4xx HTTP status code returned by the server
• object.message - what that status code likely indicates. Complete list of 4xx codes.

If the call succeeds, object.error will be false and the object will otherwise conform to the API documentation for the response object (the library will parse the returned JSON into a JavaScript object and return it with an added "error" variable with a value of false).

Sample Code

This code demonstrates both methods, using a single callback to handle both (as the response format is currently the same), and outputs their results to the console.

Install our node package: npm install avalara-taxrates

Please note that these method calls are asynchronous and will not necessarily return in order.

var taxrates = require('avalara-taxrates');

var APIKey = "YOUR API KEY - GET ONE AT taxratesapi.avalara.com";

//get tax rate by street address
taxrates.taxByAddress(APIKey, "1100 2nd Ave.", "Seattle", "WA", "USA", "98101", mycaller);

//get tax rate by zip code
taxrates.taxByZip(APIKey,"USA","91436", mycaller);

//process rate object
function mycaller(res){
  if(!res.error){
    console.log("Total Rate: " + res.totalRate);
    console.log("\nBreakdown...: ");

    for(var i in res.rates){
      console.log("\n\nRate " + (parseInt(i) + 1));
      console.log("Rate: " + res.rates[i].rate);
      console.log("Name: " + res.rates[i].name);
      console.log("Type: " + res.rates[i].type);     
      }

      //print a separator after each API call result set
      console.log("\n\n===================================\n\n");

  } else {
    console.log("ERROR:\n");
    console.log("Code: " + res.code);
    console.log("Message: " + res.message);
  }
}