Request URLs

The Arcadia Signal API servers are located at:

https://api.genability.com

You can make requests to URLs that follow these patterns:

https://api.genability.com/rest/public/{some resource path}
https://api.genability.com/rest/v1/{some resource path}

For example, here are links to get a list of LSEs, retrieve a specific LSE, and get a specific Tariff:

https://api.genability.com/rest/public/lses
https://api.genability.com/rest/public/lses/2756
https://api.genability.com/rest/public/tariffs/512

Each resource type has a dedicated documentation page that specifies the applicable URL pattern. For example, see the Tariffs page.

Authentication

Every request must contain information that identifies you as the client. We use a simple authentication approach in this initial release and will add more options as we expand our API offerings. See Authentication & Security for details.

Data Types

In addition to standard string and number inputs, we use additional input types throughout our APIs.

Array Inputs

Some fields accept multiple values as inputs, which can be specified as String arrays. For example, the customerClasses and tariffTypes fields for the Tariff method use this format. There are two ways to specify arrays as inputs. In these examples, we're requesting only "DEFAULT" and "ALTERNATIVE" tariffs:

tariffTypes=DEFAULT,ALTERNATIVE
tariffTypes=DEFAULT&tariffTypes=ALTERNATIVE

JSON Payload

Data is returned using JSON (JavaScript Object Notation). JSON is the only format we support. It's a lightweight serialization language that's compatible with many programming languages and technologies. JSON is syntactically correct JavaScript code, which means you can use the JavaScript eval() function to parse it. We have no plans to add other formats (such as XML) to our standard public RESTful APIs. However, we do support various formats and integration technologies outside of our REST APIs.

You should also use JSON in your payload when making HTTP POST and PUT calls that require it.

We do not currently support compression of REST request or response payloads, but we do support it for file uploads and downloads as part of our HTML API.

For more details on response formats, see the REST Response documentation.

HTTP Methods

Most calls to the API use HTTP GET since you'll typically be requesting one or more resources. However, some operations require other HTTP methods:

HTTP Method	POST Overload	Description
GET	n/a	Reads resources via URL, often with query string criteria
POST	n/a	Creates a new resource, or with the parameter `method`, performs a PUT or DELETE
PUT	Y	Updates an existing resource
DELETE	Y	Deletes an existing resource

JavaScript libraries and some other technologies don't easily support PUT or DELETE methods, so we provide a POST overload. Include a method parameter with a value of PUT (to update) or DELETE (to remove) to work around this limitation.

POST and PUT Body

When submitting a POST or PUT request, you'll typically need to supply a body with the request. Here's a description of headers you may need to specify:

Parameter	Type	Description
Content-type	String	This specifies the Content-Type of the body (not the content-type within the HTTP header). For most requests, set this to application/JSON. The only exception is when uploading a CSV containing meter reading data—in that case, set this value to multipart/form-data (Required)
charset	String	Set this to charset=UTF-8 (Optional)

Pagination

To help control the amount of response data returned in a call, we support pageStart and pageCount request parameters. Most API calls allow pagination since you'll typically be requesting one or more resources.

Parameter	Value	Description
pageStart	Integer	The index of the first result. Defaults to zero if not specified. (Optional)
pageCount	Integer	The number of results to return. Defaults to 25 if not specified. (Optional)

For example, you can fetch the first 100 results by setting pageStart to 0 and pageCount to 100. To fetch the next 100 results, set pageStart to 100 and pageCount to 100.

You can determine how many results matched your query by examining the count property returned in every API response. Note that we currently limit the count property to a maximum of 100,000. You should interpret 100,000 as "100,000 or more". See the Response Payload documentation for an example of a JSON response with the count property.

Searching and Sorting

Our search functionality offers flexible options for both inputs and sorting. You can search for text within one or more fields and order your results using a prioritized list of fields, each with ascending or descending sort order. All of the following search options are optional:

Parameter	Value	Description
search	String	The text string to search for. This can also be a regular expression if you set the `isRegex` flag to true (see below). (Optional)
searchOn	String	Comma-separated list of fields to search within. When `searchOn` is specified, the text in the search string field will be searched within these fields. The available fields depend on the entity being searched. Refer to the entity documentation for details on searchable fields and the default fields used when `searchOn` is not specified. (Optional)
startsWith	Boolean	When true, the search returns only results that begin with the specified search string. Otherwise, any match of the search string will be returned. Defaults to false. (Optional)
endsWith	Boolean	When true, the search returns only results that end with the specified search string. Otherwise, any match of the search string will be returned. Defaults to false. (Optional)
isRegex	Boolean	When true, the search string is treated as a regular expression and results matching the regular expression are returned. Defaults to false. (Optional)
sortOn	String	Comma-separated list of fields to sort by. This can also be input via Array Inputs (see above). (Optional)
sortOrder	String	Comma-separated list of sort orders. Possible values are `ASC` and `DESC`. Defaults to `ASC`. If your `sortOn` contains multiple fields and you want to order fields individually, you can pass a comma-separated list here (or use Array Inputs, see above). For example, if your `sortOn` contains 5 fields and your `sortOrder` contains `ASC,DESC,DESC`, these orders apply to the first three items in the `sortOn` field. The remaining two default to `ASC`. (Optional)

Getting Minimum/Standard/Extended Views

In the data definitions for various Arcadia API objects, you'll see a "Fields" column for each object property. This column can be blank, contain an "E", or contain an "M". These values correspond to properties that are in the standard set of fields, the Extended set of fields, or the Minimum set of fields, respectively.

Most requests accept a fields parameter that customizes the data included in the response. For example, pass min (for minimum) to receive only a subset of fields in your results. Pass ext (for extended) to receive all available fields. The "view" parameter modifies the response payload to return data properties flagged as part of the minimum or extended views. Not passing a fields parameter returns the standard view (this is the default).

The minimum view is designed to keep payload size small for quick loading. It's ideal for situations like building dropdown lists or autocomplete input boxes. The standard view contains commonly used properties and is good for displaying search results, performing standard computations, and similar tasks. The extended view contains data that's usually not needed but can sometimes be useful.

Value	Returns
(blank)	Common fields needed for display and most actions.
min	A subset of fields (primary and alternate keys, names and codes, important properties). Good for lookups and cross-references.
ext	All available fields.

Using SSL

All API methods should be called over SSL. You must use SSL when working with non-public data such as customer accounts and usage profiles. Ensure your client technology supports SSL (most common REST-capable client languages and technologies do).

Compressing Requests

The Arcadia API supports gzip HTTP compression for API responses. You can enable this feature in your client to immediately enjoy a significant reduction in network traffic. Our official Java client library supports this out of the box.

HTTP Response Compression

To enable HTTP response compression, simply add the following header to your requests:

Accept-Encoding: gzip