{
  "markdown": "# Sales Tax Automation Code Samples\n\nWelcome to the official `sales-tax-code-samples` repository! This repository contains examples of how to integrate and automate sales tax calculations using the [zip.tax API](https://zip.tax/) **v60** — the latest and most capable version of the API. These code samples are designed to help developers quickly implement and adapt the API in their applications.\n\n## ✨ What's New in v60\n\nVersion 60 is a major upgrade over previous API versions, introducing a completely restructured response format and a set of powerful new capabilities:\n\n| Feature | Description |\n|---|---|\n| **Structured jurisdiction rates (`baseRates`)** | Every component rate (state, county, city, special districts) is returned as a discrete object with jurisdiction type, name, description, and tax code — no more fixed `district1`–`district5` columns. |\n| **Tax summaries (`taxSummaries`)** | Pre-computed total sales and use tax rates with display-ready breakdowns, ready to show at checkout. |\n| **Sourcing rules (`sourcingRules`)** | Explicit origin- vs destination-based sourcing determination for the queried location. |\n| **Product taxability codes (`taxabilityCode`)** | Pass a TIC (Taxability Information Code) to get product-specific tax rules — reduced food rates, exemption thresholds, per-volume taxes, effective dates, and more — returned in `productDetail`. |\n| **Canadian tax rates (`countryCode=CAN`)** | GST / PST / HST / QST lookups for Canadian postal codes, with province-level breakdowns. |\n| **Historical rate lookups (`historical=YYYYMM`)** | Query the tax rates that were in effect for a past period — essential for amended returns and audits. |\n| **Extended address details (`addressDetailExtended=true`)** | Fully parsed address components (street, house number, city, county, state, postal code, country) from the geocoder. |\n| **Extended shipping rules (`shippingExtended=true`)** | State-level freight taxability rules, including whether separately-stated shipping is exempt. |\n| **Service & freight taxability** | `service` and `shipping` blocks indicate whether services and freight are taxable at the destination. |\n| **Tennessee Single Article Tax (`sat_item_total`)** | Correct local tax cap calculation for high-value single articles in Tennessee. |\n| **Lookup by address, postal code, or coordinates** | Door-level accuracy via street address or `lat`/`lng`, or all applicable rates for a postal code. |\n| **JSON and XML** | Choose your response format with `format=json` (default) or `format=xml`. |\n\n> Some features (product taxability codes, Canadian rates, historical data) are plan-level entitlements. See [zip.tax pricing](https://zip.tax/pricing) for details.\n\n## 🚀 Quick Start\n\nAll lookups are a single GET request:\n\n```\nGET https://api.zip-tax.com/request/v60?key=YOUR_API_KEY&address=200 Spectrum Center Dr, Irvine, CA 92618\n```\n\nExample v60 response (abbreviated):\n\n```json\n{\n  \"metadata\": {\n    \"version\": \"v60\",\n    \"response\": { \"code\": 100, \"name\": \"RESPONSE_CODE_SUCCESS\", \"message\": \"Successful API Request.\" }\n  },\n  \"baseRates\": [\n    { \"rate\": 0.0725, \"jurType\": \"US_STATE_SALES_TAX\",  \"jurName\": \"CA\",     \"jurDescription\": \"US State Sales Tax\",  \"jurTaxCode\": \"06\" },\n    { \"rate\": 0.005,  \"jurType\": \"US_COUNTY_SALES_TAX\", \"jurName\": \"ORANGE\", \"jurDescription\": \"US County Sales Tax\", \"jurTaxCode\": \"30\" },\n    { \"rate\": 0,      \"jurType\": \"US_CITY_SALES_TAX\",   \"jurName\": \"IRVINE\", \"jurDescription\": \"US City Sales Tax\",   \"jurTaxCode\": null }\n  ],\n  \"service\":  { \"adjustmentType\": \"SERVICE_TAXABLE\", \"taxable\": \"N\", \"description\": \"Services non-taxable\" },\n  \"shipping\": { \"adjustmentType\": \"FREIGHT_TAXABLE\", \"taxable\": \"N\", \"description\": \"Freight non-taxable\" },\n  \"sourcingRules\": { \"adjustmentType\": \"ORIGIN_DESTINATION\", \"description\": \"Destination Based Taxation\", \"value\": \"D\" },\n  \"taxSummaries\": [\n    { \"rate\": 0.0775, \"taxType\": \"SALES_TAX\", \"summaryName\": \"Total Base Sales Tax\", \"displayRates\": [ { \"name\": \"Total Rate\", \"rate\": 0.0775 } ] },\n    { \"rate\": 0.0775, \"taxType\": \"USE_TAX\",   \"summaryName\": \"Total Base Use Tax\",   \"displayRates\": [ { \"name\": \"Total Rate\", \"rate\": 0.0775 } ] }\n  ],\n  \"addressDetail\": {\n    \"normalizedAddress\": \"200 Spectrum Center Dr, Irvine, CA 92618-5003, United States\",\n    \"incorporated\": \"true\",\n    \"geoLat\": 33.65253,\n    \"geoLng\": -117.74794\n  }\n}\n```\n\n## 🔎 Request Parameters\n\n| Parameter | Description |\n|---|---|\n| `key` | **Required.** Your API key. |\n| `address` | Street address for a door-level rate lookup (geocoded and normalized). |\n| `postalcode` | US ZIP or Canadian postal code — returns all applicable rates for the code. |\n| `lat`, `lng` | Geographic coordinates for a location-based lookup. |\n| `city`, `county`, `state` | Optional filters to narrow postal-code lookups. |\n| `countryCode` | `USA` (default) or `CAN` for Canadian tax rates. |\n| `taxabilityCode` | TIC code for product-specific tax rules (e.g. `40030` = food & food ingredients). |\n| `historical` | `YYYYMM` period for historical rate lookups (e.g. `202401`). |\n| `addressDetailExtended` | `true` to include parsed address components in `addressDetail.address`. |\n| `shippingExtended` | `true` to include state-level shipping rules in `shipping.shippingExtended`. |\n| `sat_item_total` | Item total for Tennessee Single Article Tax calculation. |\n| `adjustment` | Sourcing adjustment: `auto`, `origin`, or `destination`. |\n| `format` | `json` (default) or `xml`. |\n\n## 📂 Repository Structure\n\n```\n├── Go/\n│   ├── example.go\n│   └── README.md\n├── Node/\n│   ├── example.js\n│   └── README.md\n├── Python/\n│   ├── example.py\n│   └── README.md\n├── Scala/\n│   ├── example.scala\n│   └── README.md\n└── README.md\n```\n\nEach language folder contains a runnable example demonstrating the core v60 features: address lookup, coordinate lookup, product taxability codes, Canadian rates, and extended address/shipping details.\n\n## 🛠️ Prerequisites\n\nBefore using the code samples, ensure you have:\n\n1. A [zip.tax API Key](https://zip.tax/pricing).\n2. Basic knowledge of the programming language you're working with.\n3. Installed dependencies for the selected code sample (refer to the specific sample's README).\n\n## 🔧 Getting Started\n\n1. Clone this repository:\n\n    ```bash\n    git clone https://github.com/ZipTax/sales-tax-code-samples.git\n    cd sales-tax-code-samples\n    ```\n\n2. Navigate to the directory of the programming language you want to use (e.g., `Python/`, `Go/`, `Node/`, or `Scala/`).\n\n3. Set your API key as an environment variable:\n\n    ```bash\n    export ZIPTAX_API_KEY=your_api_key_here\n    ```\n\n4. Follow the language-specific instructions to install dependencies and run the sample.\n\n### Example: Python\n\n```bash\ncd Python\npip install requests\npython example.py\n```\n\n## 📟 Response Codes\n\n| Code | Meaning |\n|---|---|\n| 100 | Successful API request |\n| 101 | Invalid or missing API key |\n| 104 | Invalid postal code |\n| 105 | Invalid query string |\n| 107 | Feature/version not enabled for your plan |\n| 108 | Rate limit exceeded (HTTP 429) |\n| 109 | Address missing, incomplete, or invalid |\n| 110 | Valid query, but no result found |\n| 111 | Invalid `historical` parameter |\n| 112 | International rates not enabled for this key |\n| 113 | Product rate rules not enabled for this key |\n\n## 📚 Documentation\n\n- [API Reference](https://docs.zip.tax)\n\n## 🤝 Contributing\n\nWe welcome contributions! If you have improvements, additional language examples, or bug fixes, please:\n\n1. Fork this repository.\n2. Create a new branch (`feature/my-feature` or `fix/issue-name`).\n3. Submit a pull request.\n\n## 📝 License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n### 🌟 Support\n\nIf you encounter any issues or have questions, feel free to open an [issue](https://github.com/ZipTax/sales-tax-code-samples/issues) or contact our [support team](https://zip.tax/contact).\n\nHappy Coding! 🚀\n",
  "bytes": 7914,
  "sha": "c6628caed82113813c6435361222dca2470681d8de0f495a837a78f269b07500",
  "repo_slug": "ziptax/sales-tax-code-samples",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_tax_zip_ziptax_c4336cda/readme"
}