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.

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
}