Utility taxes are sales and use taxes that cities and counties sometimes put in place on utility services. This page outlines the data definitions and basic API operations for utility taxes.
This data is only available to our utility customers using our Signal Product.
Data Definitions
UtilityTax
UtilityTax shares some similarities with Tariff and TariffRate objects, but has far fewer properties.
| Name | Type | Fields | Description |
|---|---|---|---|
| utilityTaxId | Integer | M | Arcadia ID of the Utility Tax |
| rateName | String | M | Utility tax name |
| fromDateTime | DateTime | The date when the utility tax became or will become effective. | |
| toDateTime | DateTime | The date when the utility tax expires. | |
| rateAmountElectricity | Decimal | M | The value of the utility tax rate for electricity service. |
| rateAmountGas | Decimal | M | The value of the utility tax rate for gas service. |
| territory | Territory | M | Territory covered by the utility tax. |
| customerClasses | Array | M | The class/classes of customer of this utility tax. |
Operations
Resource URI
GET /rest/v1/utilitytaxes
Get One Utility Tax
This endpoint retrieves a particular utility tax object by zipCode.
GET /rest/v1/utilitytaxes/{utilityTaxId}
Example
Request
GET /rest/v1/utilitytaxes/329
Response
{
"status": "success",
"count": 1,
"type": "UtilityTax",
"results": [
{
"utilityTaxId": 329,
"rateName": "Alameda County UUT",
"fromDateTime": "2014-01-01",
"toDateTime": null,
"rateAmountElectricity": 0.065,
"rateAmountGas": 0.065,
"territory": {
"territoryId": 10248,
"territoryName": "Unincorporated Alameda County",
"lseId": 734,
"usageType": "UTILITY_TAX",
"itemTypes": "COUNTY"
},
"customerClasses": [
"RESIDENTIAL",
"GENERAL",
"SPECIAL_USE"
]
}
]
}
Get a List of Utility Taxes
This allows you to search for a set of utility tax and get them back as a list of Utility Tax objects.
There is also the capability to do a text search on a few fields. One search option is location which
will search the value field of all of the territory items in a utility tax's territory. This has the effect
that location can match on a city, county, or zip code.
Request Parameters
| Name | Type | Description |
|---|---|---|
| territoryId | Integer | Arcadia ID of the Territory covered by the utility tax. |
| customerClasses | Array | A customer class specification can be one or more of RESIDENTIAL, GENERAL, or SPECIAL_USE |
| fromDateTime | DateTime | The date when the utility tax became or will become effective. |
| toDateTime | DateTime | The date when the utility tax expires. |
| lseId | Integer | Arcadia ID of the utility associated with one or more utility taxes. |
| searchOn | List | A comma-separated list of fields to search on. Currently one of utilityTaxId, taxName, or location |
| search | String | The value to search for in the utility taxes. |
| sortOn | List | A comma-separated list off fields to search on. Currently one of utilityTaxId, taxName, rateAmountElectricity, rateAmountGas, fromDateTime or toDateTime. |
| sortOrder | String | ASC for ascending or DESC for descending. |
Example
This example will get a list of utility taxes whose location contains the word "Alameda" and sorted by the tax name.
Request
{{serverUrl}}/rest/v1/utilitytaxes/?searchOn=location&search=Alameda&sortOn=rateName&lseId=734
Response
{
"status": "success",
"count": 2,
"type": "UtilityTax",
"results": [
{
"utilityTaxId": 329,
"rateName": "Alameda County UUT",
"fromDateTime": "2014-01-01",
"toDateTime": null,
"rateAmountElectricity": 0.065,
"rateAmountGas": 0.065,
"territory": {
"territoryId": 10248,
"territoryName": "Unincorporated Alameda County",
"lseId": 734,
"usageType": "UTILITY_TAX",
"itemTypes": "COUNTY"
},
"customerClasses": [
"RESIDENTIAL",
"GENERAL",
"SPECIAL_USE"
]
},
{
"utilityTaxId": 330,
"rateName": "Alameda UUT",
"fromDateTime": "2014-01-01",
"toDateTime": null,
"rateAmountElectricity": 0,
"rateAmountGas": 0,
"territory": {
"territoryId": 10298,
"territoryName": "City of Alameda",
"lseId": 734,
"usageType": "UTILITY_TAX",
"itemTypes": "CITY"
},
"customerClasses": [
"RESIDENTIAL",
"GENERAL",
"SPECIAL_USE"
]
}
],
"pageStart": 0,
"pageCount": 1
}