Out main API Portal has full descriptions and documentation for developers wanting to use the API.  This page contains various tips which we have put together based on questions and feedback from our users.

IDs - all of our data is stored with a unique ID for each record.  When accessing, using and storing data we strongly recommend you do this using the record IDs.  All IDs are fixed and will never change, while descriptive fields and other content fields may be updated or modified. 

 

Parameters

All parameters are in SI base units, unless otherwise explicitly stated.  Notable exceptions are:

• CSA - cross-sectional areas are generally in mm²

It is the developer's responsibility to ensure that all parameters are validated and within range.

The following are intended to provide general guidance on specific parameters:

• Power Factor - between -1 and 1.  A value of 0 indicates a d.c. circuit.  Positive values of power factor are used for a lagging load (i.e. motor) and negative values for a leading load (i.e. capacitor).

See also: API Input Parameters

Response

Examples of the response are given when you try out API calls in the main portal. Additionally:

• 200 OK - the body will contain the response data (or '[]' for empty lists, 'null' for empty structures)
• 400 Bad Response - the response was not formatted correctly (i.e. a number out of range), with an error message

 

Complex Numbers

Many of our calculations are carried out using complex numbers, and to avoid losing information we return the full complex details.  For users not familiar with complex numbers, you can use the following as a guide to interpretation:

Voltage: value [m_magnitude], phase angle [m_phase]

Current: value [m_magnitude], phase angle [m_phase], power factor [m_cosPhase]

Power: W [m_real], VAr [m_imaginary], VA [m_magnitude], power factor [m_cosPhase]

Validation

Unlike many API which return highly structured data in response to fixed inputs, our API carries out complex calculations for a large number of inputs.  The number of input permutations (cables, installations methods, sizing standards, electrical system configurations, etc.) is almost limitless.  While we carry out a range of validation checks for common input errors, it is not feasible nor beneficial to try and validation every possible permutation of inputs.  The client is ultimately responsible for ensuring that inputs are consistent and form a realistic system.  Out API provides consistent data, but if this is mixed up by the client (for example requesting a BS 7671 capacity calculation, but passing an ERA 69-30 installation method) it is likely to result in an error.

As mentioned, we do provide checking for a variety of common input errors, and if found a formatted error message (status code 400) will be returned.