Harvest API Documentation

Commands

All requests need to contain the output_type parameter, this should be set to application/json for now.

All requests need to contain the api_key parameter, this should be set to your API key, if you don't have one please contact Harvest Support.

The Harvest API is not intended to be used from within client side script such as Javascript as this will open up your API key for others to view, as such we have not added headers to allow CORS (attempts to do so in browsers such as Chrome will throw an error, typically something like "Access to XMLHttpRequest at URL from origin YourWebServer has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource". The intended usage is for you to implement the requests server side, at this point you will be able to utilise the likes of AJAX to make a call to your own server which will then access the Harvest API.

Your requests may result in errors if you fail to include required parameters (these will be noted by the command type and the required column). You may also see errors if you fail to adhere to the rate limits

Get User Site List

Command Type

get_user_site_list

Request Type

GET

Output Types Supported

application/json

Details

Returns JSON object containing an array of site objects for sites that the given API Key or User Name & Password has specific access to.

By default the site object will contain a 'site_options' object with an array of 'locations' for the site. Setting the optional parameter 'include_all_options=1' will return the other options related to each site.

This command supports pagination.

Parameters

Example Usage

Response 

List of sites that your API key has access to, includes site id's that can be used in other commands.

Get Site Image

Command Type

get_site_image

Request Type

GET

Output Types Supported

application/json

Details

Returns JSON object containing a base64 encoded image along with a '_links' object containing 'prev' / 'next' links to retrieve additional images (where available) for the given 'site_id'.

If no 'image_id' is provided then it will get the latest available image.

A 'site_id' must always be provided for security reasons. We do not allow retrieval of images based on the 'image_id' alone.

Parameters

Example Usage

Response 

JSON object containing a base64 encoded image along with a '_links' object containing 'prev' / 'next' links to retrieve additional images (where available) for the given 'site_id'.

Get Graph List

Command Type

get_graph_list

Request Type

GET

Output Types Supported

application/json

Details

Returns JSON object containing graph objects for the given site_id.

Each object should contain the 'graph_id', 'graph_name', 'graph_sort_order' and an array of traces that include 'trace_id', 'trace_name', 'trace_order'.

Hidden graphs and traces will be suppressed if the user does not have access to them, otherwise they will include 'graph_hidden' or 'trace_hidden' if hidden.

Includes the trace id's that are needed for requesting data

Parameters

Example Usage

Response 

Returns JSON object containing graph objects for the given site_id.

Get Data

Command Type

get_data

Request Type

GET

Output Types Supported

application/json

Details

Returns JSON object containing data for the specified trace.

If the start_time parameter is omitted then the system will return the latest log. If you wish to retrieve the latest data for a number of traces, consider using the Get Latest Data command instead

If the start_time (UTC) parameter is set then it will return up to 100 logs from the specified start time. In the scenario more than 100 logs are available a "next" link will be provided for use in obtaining the next set of logs, this will be provided until there are no longer more than 100 logs. It is advisable to use the "next" link rather than manually adjusting the start parameter.

This command supports pagination.

Parameters

Example Usage

Request data from specific time
https://live.harvest.com/api.php?output_type=application/json&command_type=get_data&api_key=YOUR_API_KEY&trace_id=TRACE_ID&start_time=2018-06-01+12:00:00

Request latest data
https://live.harvest.com/api.php?output_type=application/json&command_type=get_data&api_key=YOUR_API_KEY&trace_id=TRACE_ID

Response 

JSON object containing data for the specified trace. If a start time is set and there are more than 100 logs available then a links object will also be present containing next and prev links.

Returned timestamps are in UTC, timezone names are added for the purpose of converted data to the sites local time if necessary.

Get Latest Data

Command Type

get_latest_data

Request Type

GET

Output Types Supported

application/json

Details

Returns JSON object containing the latest available data for the specified traces.

The trace ids set can span across multiple sites, however the API Key used must still have permission to access each individual site.

Parameters

Example Usage

https://live.harvest.com/api.php?output_type=application/json&command_type=get_latest_data&api_key=YOUR_API_KEY&trace_ids=[TRACE_ID_1,TRACE_ID_2,TRACE_ID_3, ..., TRACE_ID_N]

Response 

JSON object containing the latest data for the specified traces. It should not be assumed that all traces are from the same point in time, especially when requesting across multiple sites. Utilise the unix_time parameter in each of the individual trace objects to get the timestamp for each trace id.

Returned timestamps are in UTC, timezone names are added for the purpose of converted data to the sites local time if necessary.

The unix_time returned is the time of the last log whereas the statistics (hourly/ daily totals) are relative to the time of the request.

Get Summary Data

Command Type

get_summary_data

Request Type

GET

Output Types Supported

application/json

Details

Returns JSON object containing summary data for specified traces.

Summary data may include: Average, Min, Max, GDD, RCU, Total (where appropriate).

If the date parameter is specified the 'day' summary data will be for midnight to midnight of the specified date.
The date requested should be in the site local timezone.
When no date is specified the day summary data will be from midnight of the current day to the time of the request.

When the season parameter is set to 1, seasonal statistics will be included.

If the date parameter is specified the 'season' summary data will be for the relevant season (configured for the site) that falls within the specified date.
When no date is specified the season summary data will be for the current season.

Parameters

Example Usage

https://live.harvest.com/api.php?output_type=application/json&command_type=get_summary_data&api_key=YOUR_API_KEY&trace_ids=[TRACE_ID_1,TRACE_ID_2,TRACE_ID_3, ..., TRACE_ID_N]

Response 

JSON object containing the summary data for the specified traces.

Returned timestamps are in the sites local timezone as indicated by the time_zone returned in the response.

API Information

Pagination

Commands that support pagination may end up responding with a "_links" section. This will occur if there is more data available 

Rate Limit

API requests are limited to 200 requests per minute.

No more than two (2) concurrent connections are allowed. N.B. This is not currently enforced; however, breaches are logged for review.