Utility Tax

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	Genability 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "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	Genability 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	Genability 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 sorts by the tax name.

Request

/rest/v1/utilitytaxes/?searchOn=location&search=Alameda&sortOn=rateName&lseId=734

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "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
}