Getting Started

Welcome to the GoodVat Developer Documentation. GoodVat is building simple, automatic sales tax and VAT calculation for online sellers — with plugins for Shopify, WooCommerce, and more platforms on the way. This documentation covers the building blocks behind that: address standardization, geocoding, and tax calculation, each available directly as an API today.

This guide will walk you through setting up your credentials and making your first live API request to standardize a global address.

---

Quickstart

Follow these steps to make your first request to the GoodVat API.

1. Create an API Key

   Server-to-server API requests require a bearer authentication key. Go to your GoodVat Dashboard API Keys page, click Create API Key, and copy your secret key (gv_live_...).

2. Subscribe to Address Standardization

   Visit the Products Dashboard and enable Address Standardization for your organization. Accounts include instant access.

3. Make Your First API Request

   Pass your secret key as a Bearer token in the Authorization header when sending requests to the Address Standardization endpoint:

cURL

curl -X POST "https://api.goodvat.com/v1/address/normalize" \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "10 Downing Street, London SW1A 2AA, UK"
  }'

Node.js

const response = await fetch('https://api.goodvat.com/v1/address/normalize', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.GOODVAT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: '10 Downing Street, London SW1A 2AA, UK',
  }),
});

const address = await response.json();
console.log('Standardized Address:', address.houseNumber, address.road, address.city, address.postcode);

Python

import os
import requests

api_key = os.environ.get("GOODVAT_API_KEY")

response = requests.post(
    "https://api.goodvat.com/v1/address/normalize",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "query": "10 Downing Street, London SW1A 2AA, UK",
    },
)

address = response.json()
print("Standardized Address:", address["houseNumber"], address["road"], address["city"], address["postcode"])

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func main() {
  payload := map[string]string{
    "query": "10 Downing Street, London SW1A 2AA, UK",
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("POST", "https://api.goodvat.com/v1/address/normalize", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("GOODVAT_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  fmt.Println("Response Status:", resp.Status)
}

PHP

<?php
$apiKey = getenv('GOODVAT_API_KEY');

$ch = curl_init('https://api.goodvat.com/v1/address/normalize');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'query' => '10 Downing Street, London SW1A 2AA, UK'
]));

$response = curl_exec($ch);
curl_close($ch);

$address = json_decode($response, true);
echo "Road: " . $address['road'];

---

Response Payload

A successful request returns HTTP 200 OK with granular structured components and canonical string expansions. Only fields the parser was confident about are included:

200 OK

{
  "houseNumber": "10",
  "road": "downing street",
  "postcode": "sw1a 2aa",
  "city": "london",
  "country": "GBR",
  "expansions": [
    "10 downing street london sw1a 2aa uk",
    "10 downing street london sw1a 2aa united kingdom"
  ]
}

Key Response Fields

Field	Description
expansions	Canonical, fully expanded string variations of the input address (string[]), standardizing abbreviations (e.g. st → street, ave → avenue, ste → suite) for turnkey search indexing and deduplication.
houseNumber	Street or building number.
road	Street name or thoroughfare.
unit	Apartment, suite, or unit number.
postcode	Postal or ZIP code.
city	City, town, or village.
state	State, province, or region.
country	ISO 3166-1 alpha-3 country code, when present in the input.

See the Address Standardization page for the full field reference, expansion engine details, and production use cases.

---

Product Suite

GoodVat provides an expanding suite of global commerce tax and address utilities:

Address Standardization

Live now. Standardize and format global customer shipping & billing addresses for accurate tax jurisdiction matching.

USA Geocoding

Coming soon. High-precision rooftop geocoding across all 50 US states to resolve complex local sales tax boundaries.

Global Tax Calculation

Coming soon. Real-time sales tax, VAT, and GST calculation across 14,000+ jurisdictions worldwide.

---

Next Steps

Now that you’ve sent your first request, explore the rest of our documentation to integrate GoodVat into your production systems:

• Authentication Guide — Key security best practices, header formats, and error handling.
• Address Standardization — How the standardization engine works, plus use cases across tax, shipping, fraud, and more.