API Requests

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:

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:

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.

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:

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.

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