Getting Started

Golang

This guide walks you through how to set up and use the zip.tax API in a Golang application.

Prerequisites

Before getting started, ensure you have the following:

Basic knowledge of Golang.
A Golang development environment.
An API key. To subscribe for a new key, please choose a subscription. The guide below uses a Geo level subscription.

1

Install Required Libraries

For making HTTP requests, we'll use Golang's standard net/http package. Additionally, we'll use encoding/json for parsing JSON responses.

2

Start the Golang Project

Create a new project directory and initialize a new module:

Bash

 mkdir ziptax-golang && cd ziptax-golang
go mod init ziptax-golang

3

The Code

Here is a complete example of a simple Golang application that queries the zip.tax API for sales tax information.

 package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
)

//
// ---------- Response Models for v60 ----------
//

type ZipTaxResponse struct {
	Metadata      Metadata        `json:"metadata"`
	BaseRates     []BaseRate      `json:"baseRates"`
	Service       Adjustment       `json:"service"`
	Shipping      Adjustment       `json:"shipping"`
	SourcingRules Adjustment       `json:"sourcingRules"`
	TaxSummaries  []TaxSummary     `json:"taxSummaries"`
	AddressDetail AddressDetailV60 `json:"addressDetail"`
}

type Metadata struct {
	Version  string            `json:"version"`
	Response MetadataResponse  `json:"response"`
}

type MetadataResponse struct {
	Code        int    `json:"code"`
	Name        string `json:"name"`
	Message     string `json:"message"`
	Definition  string `json:"definition"`
}

type BaseRate struct {
	Rate          float64 `json:"rate"`
	JurType       string  `json:"jurType"`
	JurName       string  `json:"jurName"`
	JurDescription string `json:"jurDescription"`
	JurTaxCode    *string `json:"jurTaxCode"` // nullable
}

type Adjustment struct {
	AdjustmentType string `json:"adjustmentType"`
	Taxable        string `json:"taxable"`
	Description    string `json:"description"`
}

type TaxSummary struct {
	Rate         float64        `json:"rate"`
	TaxType      string         `json:"taxType"`
	SummaryName  string         `json:"summaryName"`
	DisplayRates []DisplayRate  `json:"displayRates"`
}

type DisplayRate struct {
	Name string  `json:"name"`
	Rate float64 `json:"rate"`
}

type AddressDetailV60 struct {
	NormalizedAddress string  `json:"normalizedAddress"`
	Incorporated      string  `json:"incorporated"`
	GeoLat            float64 `json:"geoLat"`
	GeoLng            float64 `json:"geoLng"`
}

//
// ---------- API Caller ----------
//

func getSalesTaxV60(address string, apiKey string) (*ZipTaxResponse, error) {
	endpoint := fmt.Sprintf(
		"https://api.zip-tax.com/request/v60?key=%s&address=%s",
		apiKey,
		url.QueryEscape(address),
	)

	resp, err := http.Get(endpoint)
	if err != nil {
		return nil, fmt.Errorf("failed to make API request: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("unexpected HTTP status %d", resp.StatusCode)
	}

	var result ZipTaxResponse
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return nil, fmt.Errorf("failed to parse JSON: %w", err)
	}

	return &result, nil
}

//
// ---------- Example Main ----------
//

func main() {
	apiKey := "your_api_key_here"
	address := "200 Spectrum Center Drive, Irvine, CA 92618"

	taxInfo, err := getSalesTaxV60(address, apiKey)
	if err != nil {
		log.Fatalf("Error fetching sales tax: %v", err)
	}

	fmt.Println("----- ZipTax API v60 Response -----")

	fmt.Printf("Normalized Address: %s\n", taxInfo.AddressDetail.NormalizedAddress)
	fmt.Printf("Coordinates: %f, %f\n", taxInfo.AddressDetail.GeoLat, taxInfo.AddressDetail.GeoLng)

	// Example: Get the total SALES tax (from taxSummaries)
	for _, summary := range taxInfo.TaxSummaries {
		if summary.TaxType == "SALES_TAX" {
			fmt.Printf("Total Sales Tax: %.2f%%\n", summary.Rate*100)
		}
	}
}

Explanation of the Code

API Request: The getSalesTax function constructs a URL with the API key and an address, makes a GET request, and parses the response.
Response Parsing: The response JSON is unmarshalled into a Response struct for easy access to sales tax details.
Display Results: The main function prints the normalized address, lat/lng, and sales tax rate for the specified address code. You can use any of the Response struct values here to output the data you need.

4

Run the Application

Save the code to a file (e.g., main.go), then run the program:

Bash

 go run main.go

You should see output similar to this:

Plain text

Normalized Address: 200 Spectrum Center Dr, Irvine, CA 92618-5003, United States
Coordinates: 33.652530, -117.747940
Total Sales Tax: 7.75%

Conclusion

Integrating the zip.tax API into your Golang application is straightforward. By following this guide, you can enhance your application with accurate sales tax information based on address. For more details, refer to the official documentation above at Getting Started.

If you have any questions or feedback, feel free to email us at support@zip.tax. Happy coding!

Sections