(Last updated December 22, 2020)
NOTE TO AQUACUE API USERS IN CANADA
In compliance with Canadian cross-border data regulations, your facility data is or already has been moved to Canada. As a result, if you login to AquaCUE via beaconama.ca you should adjust all of your API calls to address endpoints at api.beaconama.ca.
For example, change
https://api.beaconama.net/v1/eds/read/
to
https://api.beaconama.ca/v1/eds/read/
This change affects all API endpoint calls for facilities that login to beaconama.ca.
The Export Data Services v1 API provides the following methods to support data export functionality.
| Method | Description |
| POST | Post a request to export aggregate flow data and reads at a start and end date. |
| Method | Description |
| POST | Post a request to export aggregated total consumption. |
| Method | Description |
| POST | Post a request to export the latest billing read data using Format C input files. |
| Method | Description |
| POST | Post a request to export flow data within a date range. |
| Method | Description |
| POST | Post a request to export the latest billing read data. |
| Method | Description |
| POST | Post a request to export a list of alerts from meters, encoders and endpoints along with alert start and end dates. |
| Method | Description |
| GET | Retrieves the current status of the export processing, including a URL to download the export results, when available. |
Export Data Services
POST /v1/eds/flow
Submits a request to retrieve the export aggregate flow data and reads at a start and end date. See the Export Data Services API Process Diagram.
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
Parameters:
| Parameter Name | Required | Type | Description |
| buildingType | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AquaCUE Monitor. | |
| continuousFlowExpected | Text | Yes/No. | |
| dhsCode | Text | Department of Health Services code used to identify water sources. | |
| district | Text | A unique identifier for the district. | |
| endDate |  |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| funding | Text | Label for filtering in AquaCUE Monitor. | |
| hasEndpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| headerColumns | Text | Comma-separated list of column names to include in the output:
• Account_ID |
|
| limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| mainUse | Text | Label for filtering in AquaCUE Monitor. | |
| meterId | Text | An identifier for the meter; can be provided multiple times. | |
| meterSize | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) | |
| lastMeterID | Text | Optional identifier used for pagination of meter results. | |
| outputFormat | Text | Output format to use: • csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| csvSeparator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,) , semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| csvQuotingOption | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| route | Text | Identifier of the route or book the metered service belongs to. | |
| servicePointClassCode | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| servicePointCycle | Text | An identifier used to denote the billing cycle name. | |
| site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AquaCUE Monitor. | |
| startDate | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| unit | Text | Unit in which to present flow data:
• acrefeet |
|
| waterType | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AquaCUE Monitor. |
POST EDS::Request
POST /v1/eds/flow
[sourcecode lang=”bash”]
# Use these parameters to post a request to export aggregate
# flow data and reads at a start and end date.
#
servicePointCycle=11111
startDate=2016-02-01T00:00:00Z
endDate=2016-02-29T23:59:59Z
headerColumns=Account_ID,Meter_ID,Flow
#
[/sourcecode]
curl
[sourcecode lang=”bash”]
# Use this cURL statement to post a request to export aggregate
# flow data and reads at a start and end date.
#
curl -X POST -uusername:password \
-H “Content-Type: application/x-www-form-urlencoded” \
-d servicePointCycle=11111 \
-d district=las \
-d startDate=2016-02-01T00:00:00Z \
-d endDate=2016-02-29T23:59:59Z \
-d headerColumns=Account_ID,Meter_ID,Flow \
https://api.beaconama.net/v1/eds/flow
#
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034”
}
[/sourcecode]
Response
Returns EDSNew object.
202 Accepted – The EDS request has been submitted successfully and the status can be followed at the statusUrl location.
POST /v1/eds/consumption
Submits a request to retrieve aggregated consumption data at a start and end date.
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
Parameters:
| Parameter Name | Required | Type | Description |
| endDate | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| hasEndpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| headerColumns | |
Text | Comma-separated list of column names to include in the output:
Day_of_Week Num_Meters counts the total number of meters with >0 flow. |
| limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| buildingType | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AquaCUE Monitor. | |
| dhsCode | Text | Department of Health Services code used to identify water sources. | |
| district | Text | A unique identifier for the district. | |
| funding | Text | Label for filtering in AquaCUE Monitor. | |
| mainUse | Text | Label for filtering in AquaCUE Monitor. | |
| site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AquaCUE Monitor. | |
| waterType | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AquaCUE Monitor. | |
| continuousFlowExcepted | Text | Yes/No. | |
| meterId | Text | An identifier for the meter; can be provided multiple times. | |
| meterSize | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| lastMeterID | Text | Optional identifier used for pagination of meter results. | |
| outputFormat | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| csvSeparator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,) , semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| csvQuotingOption | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| resolution | Text | Aggregation level:
|
|
| servicePointClassCode | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| servicePointCycle | Text | An identifier used to denote the billing cycle name. | |
| route | Text | Identifier of the route or book the metered service belongs to. | |
| startDate | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| tolerance | Number | How many hours to look backward for the latest reading. Must be >= 24. | |
| unit | Text | Unit in which to present flow data:
• acrefeet |
POST EDS::Request
POST /v1/eds/consumption
[sourcecode lang=”bash”]
# Use these parameters to post a request to export aggregate
# consumption for a start and end date at a given tolerance.
#
servicePointCycle=11111
startDate=2016-02-01T00:00:00Z
endDate=2016-02-29T23:59:59Z
tolerance=72
headerColumns=Flow,Flow_Time,Flow_Unit
#
[/sourcecode]
curl
[sourcecode lang=”bash”]
# Use this cURL statement to post a request to export aggregate
# consumption data at a start and end date and a given tolerance.
#
curl -X POST -uusername:password \
-H “Content-Type: application/x-www-form-urlencoded” \
-d servicePointCyce=11111 \
-d startDate=2016-02-01T00:00:00Z \
-d endDate=2016-02-29T23:59:59Z \
-d tolerance=72 \
-d headerColumns=Flow,Flow_Time,Flow_Unit \
https://api.beaconama.net/v1/eds/consumption
#
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034”
}
[/sourcecode]
Response
Returns EDSNew object.
202 Accepted – The EDS request has been submitted successfully and the status can be followed at the statusUrl location.
• location header points to statusUrl
• location header points to statusUrl
POST /v1/eds/formatc
Post a request to export the latest billing read data using a Format C input file within the given tolerance. This API endpoint uses the meter and account information from the given file as its filters. The returned data will be in Format C, per the original file, rather than in CSV format.
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
Parameters:
| Parameter Name | Required | Type | Description |
| data | |
File | The input file in Format C from which to extract the meter and account information. |
| date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| tolerance | |
Number | How many hours to look backward for the latest reading. Must be >= 24. |
POST EDS::Request
POST /v1/eds/formatc
[sourcecode lang=”bash”]
# Use these parameters to post a request to export
# the latest billing read data using a Format C input file,
# within the given tolerance.
#
data=$HOME/Desktop/my-format-c-data.txt
date=2015-08-23T22:06:09Z
tolerance=72
#
[/sourcecode]
curl
[sourcecode lang=”bash”]
# Use this cURL statement to post a request to export
# the latest billing read data using a Format C input file,
# within the given tolerance.
#
curl -uusername:password \
-H “Content-Type: application/x-www-form-urlencoded” \
-F data=@$HOME/Desktop/my-format-c-data.txt \
-F date=2015-08-23T22:06:09Z \
-F tolerance=72 \
https://api.beaconama.net/v1/eds/formatc
#
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034”
}
[/sourcecode]
Response
Returns EDSNew object.
202 Accepted – The EDS request has been submitted successfully and the status can be followed at the statusUrl location.
• location header points to statusUrl
POST /v1/eds/range
Submits a request to export flow data within a date range.
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
Parameters:
| Parameter Name | Required | Type | Description |
| buildingType | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AquaCUE Monitor. | |
| continuousFlowExpected | Text | Yes/No. | |
| dhsCode | Text | Department of Health Services code used to identify water sources. | |
| district | Text | A unique identifier for the district. | |
| endDate | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided |
| funding | Text | Label for filtering in AquaCUE Monitor. | |
| hasEndpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| headerColumns | Text | Comma-separated list of column names to include in the output:
• Account_Full_Name |
|
| limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 10000. Must be between 1 and 10000. | |
| mainUse | Text | Label for filtering in AquaCUE Monitor. | |
| meterId | Text | An identifier for the meter; can be provided multiple times. | |
| meterSize | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) | |
| lastMeterID | Text | Optional identifier used for pagination of meter results. | |
| outputFormat | Text | Output format to use: • csv produces simple CSV files with quoted strings when needed (default) • json: produces JSON for use by other programs |
|
| csvSeparator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,) , semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| csvQuotingOption | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| resolution | Text | Aggregation level:
• daily (default) |
|
| route | Text | Identifier of the route or book the metered service belongs to. | |
| servicePointClassCode | Text | Identifier for this service point’s classification/category in the budgeting system, e.g., residential, commercial, irrigation, etc. | |
| servicePointCycle | Text | An identifier used to denote the billing cycle name. | |
| site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AquaCUE Monitor. | |
| startDate | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| unit | Text | Unit in which to present flow data:
• acrefeet |
|
| waterType | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AquaCUE Monitor. |
POST EDS::Request
POST /v1/eds/range
[sourcecode lang=”bash”]
# Use these parameters to submit a request to export
# flow data within a date range.
#
servicePointCycle=11111
startDate=2015-08-23T22:06:09Z
endDate=2015-12-31T22:06:09Z
headerColumns=Account_ID,Meter_ID,Read
#
[/sourcecode]
curl
[sourcecode lang=”bash”]
# Use this cURL statement to post a submit a request
# to export flow data within a date range.
#
curl -uusername:password \
-H “Content-Type: application/x-www-form-urlencoded” \
-F servicePointCycle=11111
-F district=las \
-F startDate=2015-08-23 \
-F endDate=2015-12-31T22:06:09Z \
-F headerColumns=Account_ID,Meter_ID,Read \
https://api.beaconama.net/v1/eds/range
#
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034”
}
[/sourcecode]
Response
Returns EDSNew object.
202 Accepted – The EDS request has been submitted successfully and the status can be followed at the statusUrl location.
• location header points to statusUrl
POST /v1/eds/read
Submits a request to retrieve the latest billing read data for the provided filters and tolerance.
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
Parameters:
| Parameter Name | Required | Type | Description |
| buildingType | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AquaCUE Monitor. | |
| continuousFlowExpected | Text | Yes/No. | |
| date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| dhsCode | Text | Department of Health Services code used to identify water sources. | |
| district | Text | A unique identifier for the district. | |
| funding | Text | Label for filtering in AquaCUE Monitor. | |
| hasEndpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| headerColumns | Text | Comma-separated list of column names to include in the output:
• Account_ID |
|
| includeReads | Text | Export records for all meters, meters with or meters without current billing reads. If not provided, defaults to all.
Enter one of: Current billing reads = a billing read that falls within the given tolerance setting. If the current read = previous read or if the current read = 0, then the read will be returned. |
|
| limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 10000. Must be between 1 and 10000. | |
| mainUse | Text | Label for filtering in AquaCUE Monitor. | |
| meterId | Text | An identifier for the meter; can be provided multiple times. | |
| meterSize | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) | |
| lastMeterID | Text | Optional identifier used for pagination of meter results. | |
| outputFormat | Text | Output format to use: • csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| csvSeparator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,) , semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| csvQuotingOption | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| route | Text | Identifier of the route or book the metered service belongs to. | |
| servicePointClassCode | Text | Identifier for this service point’s classification/category in the budgeting system, e.g., residential, commercial, irrigation, etc. | |
| servicePointCycle | Text | An identifier used to denote the billing cycle name. | |
| site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AquaCUE Monitor. | |
| syncRegisters | Boolean | True to synchronize read and read times for registers on compound meters based on the syncTolerance setting (see below). If not provided, defaults to False. | |
| syncTolerance | Number | How many minutes to look backward for the latest reading. If not provided, defaults to 15 minutes. | |
| tolerance | Number | How many hours to look backward for the latest reading. Must be >= 24. If not provided, EDS returns the last read available for each meter. | |
| waterType | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AquaCUE Monitor. |
POST EDS::Request
POST /v1/eds/read
[sourcecode lang=”bash”]
# Use these parameters to submit a request to retrieve
# the latest billing read data for the provided filters
# and tolerance.
#
meterId=abc123
meterId=xyz789
date=2015-08-23T22:06:09Z
tolerance=72
headerColumns=Account_ID,Meter_ID,Read
#
[/sourcecode]
curl
[sourcecode lang=”bash”]
# Use this cURL statement to post a submit a request
# to retrieve the latest billing read data for
# the provided filters and tolerance.
#
curl -uusername:password \
-H “Content-Type: application/x-www-form-urlencoded” \
-F meterId=abc123 \
-F meterId=xyz789 \
-F date=2015-12-31T22:06:09Z \
-F tolerance=72 \
-F headerColumns=Account_ID,Meter_ID,Read \
https://api.beaconama.net/v1/eds/read
#
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034”
}
[/sourcecode]
Response
Returns EDSNew object.
202 Accepted – The EDS request has been submitted successfully and the status can be followed at the statusUrl location.
POST /v1/eds/exception_range
Submits a request to retrieve a report of historical exceptions
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
Parameters:
| Parameter Name | Required | Type | Description |
| buildingType | Text | Optional building type (eg, ‘retail’, ‘dining’, ‘apartments’) label | |
| continuousFlowExpected | Text | Yes/No | |
| dhsCode | Text | Optional Department of Health Services code | |
| district | Text |
A unique identifier for the district |
|
| endDate | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z“.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided |
| funding | Text | Optional funding label | |
| hasEndpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both |
|
| headerColumns | Text | Comma-separated list of column names to include in the output:
|
|
| limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 10000. Must be between 1 and 10000 | |
| mainUse | Text | Optional main use label | |
|
meterId |
Text |
An identifier for the meter; can be provided multiple times |
|
| meterSize | Text | Numeric size of the meter (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) | |
| offset | Number | Optional starting offset (0-based) for pagination of meter results. | |
| outputFormat | Text | Output format to use:
|
|
| route | Text | Identifier of the route or book the metered service belongs to | |
| servicePointClassCode | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
|
servicePointCycle |
Text |
An identifier used to denote the billing cycle name |
|
| site | Text | Optional site (eg, ‘North Campus’, ‘Uptown Village’) label | |
| startDate | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z“.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided |
| waterType | Text | Optional water type (eg, ‘hot’, ‘cold’, ‘potable’, ‘reclaimed’) label |
POST EDS::Request
POST /v1/eds/exception_range
[sourcecode lang=”bash”]
servicePointCycle=11111
startDate=2016-02-01T00:00:00Z
endDate=2016-02-29T23:59:59Z
headerColumns=Account_ID,Meter_ID,Exception_Start_Date,Exception_End_Date,Exception
[/sourcecode]
curl
[sourcecode lang=”bash”]
curl -X POST -uusername:password \
-H “Content-Type: application/x-www-form-urlencoded” \
-d servicePointCycle=11111 \
-d district=las \
-d startDate=2016-02-01T00:00:00Z \
-d endDate=2016-02-29T23:59:59Z \
-d headerColumns=Account_ID,Meter_ID,Exception_Start_Date,Exception_End_Date,Exception \
https://api.beaconama.net/v1/eds/exception_range
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034”
}
[/sourcecode]
Response
Returns EDSNew object.
202 Accepted – The EDS request has been submitted successfully and the status can be followed at the statusUrl location.
• location header points to statusUrl
GET /v1/eds/status/{edsUUID}
Retrieves the status of the billing read export data request for the provided EDS UUID.
Parameters:
| Parameter Name | Required | Type | Description |
| edsUUID | |
UUID | An identifier for the request. |
GET EDS::Request
[sourcecode lang=”bash”]
# # Use this command to retrieve the latest
# billing read export status.
#
GET /v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034
#
[/sourcecode]
curl
[sourcecode lang=”bash”]
# Use this cURL statement to retrieve
# the billing read export status.
#
curl -uusername:password https://api.beaconama.net/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034
#
[/sourcecode]
GET EDS status::Response::Queued
[sourcecode lang=”bash”]
{
“state”: “queue”,
“message”: “Export operation queued for processing.”,
“queueTime”: “2015-01-14T23:50:59Z”
}
[/sourcecode]
GET EDS status::Response::Running
[sourcecode lang=”bash”]
{
“startTime”: “2015-01-15T00:00:00Z”,
“state”: “run”,
“progress”: {
“percentComplete”: “12.0”,
“ETA”: “2015-01-15T01:02:31Z”,
“message”: “performing validation”
},
“message”: “Export operation running.”,
“queueTime”: “2015-01-14T23:50:59Z”
}
[/sourcecode]
GET EDS status::Response::Exception
[sourcecode lang=”bash”]
{
“startTime”: “2015-01-15T00:00:00Z”,
“state”: “exception”,
“endTime”: “2015-01-15T01:02:30Z”,
“message”: “Export operation had problems.”,
“queueTime”: “2015-01-14T23:50:59Z”
}
[/sourcecode]
GET EDS status::Response::Complete
[sourcecode lang=”bash”]
{
“startTime”: “2015-01-15T00:00:00Z”,
“state”: “done”,
“endTime”: “2015-01-15T01:02:30Z”,
“message”: “Export operation succeeded.”,
“queueTime”: “2015-01-14T23:50:59Z”,
“reportUrl”: “/v1/content/. . .”
}
[/sourcecode]
Response
Returns EDSStatus object.
CSV Export Formats
Flow CSV Export Formats
This CSV file format definition describes the billing read output of AquaCUE. Each row represents a reading off a single register from a meter. Identifiers, read data and read time are always provided. The remaining fields such as reader initials and read codes are included if readings were recorded using a Badger Meter mobile reading system. Readings obtained from fixed network and cellular endpoints do not provide this information.
| Column Name | Max Length | Format | Description |
| Account_ID | 32 | Text | Identifier of the Account used for billing purposes. |
| Location_ID | 40 | Text | Unique identifier for the location where the service is being provided. |
| Service_Point_ID | 40 | Text | An identifier used to distinguish between multiple service hookups at the same Location. The combination of Location ID and Service Point ID represents a single point to which a meter is to be attached. |
| Meter_ID | 24 | Text | Identifier of the meter. It must be unique and is required. |
| Endpoint_SN | 20 | Text | Serial number of the endpoint paired with the specified meter. |
| Point_1_Read | 9 | Number | The first reading available within the requested date range. |
| Point_1_Read_Time | 22 | YYYY-MM-DD hh:mm:ss |
Date and time of the first read. (2014-09-10 10:39:41) |
| Point_2_Read | 9 | Number | The last reading available within the requested date range. |
| Point_2_Read_Time | 22 | YYYY-MM-DD hh:mm:ss |
Date and time of the last read. (2014-09-10 10:39:41) |
| Read_Unit | 20 | Text | The unit of measurement for the reads. |
| Time_Zone | 40 | Text | Time zone of the meter. |
| Flow | 9 | Number | Aggregate flow between the start and end dates pro. |
| Flow_Units | 20 | Text | The unit of measurement for the flow. |
Read CSV Export Formats
This CSV file format definition describes the billing read output of AquaCUE. Each row represents a reading off a single register from a meter. Identifiers, read data and read time are always provided. The remaining fields such as reader initials and read codes are included if readings were recorded using Badger Meter mobile reading system. Readings obtained from fixed network and cellular endpoints do not provide this information.
| Column Name | Max Length | Format | Description |
| Account_ID | 32 | Text | Identifier of the Account used for billing purposes. |
| Location_ID | 40 | Text | Unique identifier for the location where the service is being provided. |
| Service_Point_ID | 40 | Text | An identifier used to distinguish between multiple service hookups at the same Location. The combination of Location ID and Service Point ID represents a single point to which a meter is to be attached. |
| Meter_ID | 24 | Text | Identifier of the meter. It must be unique and is required. |
| Register_Number | 1 | Text | Identifies whether a meter is a single or compound meter. For single meters, the value will be blank or 0. For compounds, a 0 or an L identifies low-flow registers. A 2 or an H identifies high-flow registers. |
| Endpoint_SN | 20 | Text | Serial number of the endpoint paired with the specified meter. |
| headerColumns | Text | Comma-separated list of column names to include in the output:
• Account_ID |
|
| Read_Method | 7 | Text | How the meter reading was obtained: Network, AMR, Manual or Utility. |
| Read | 9 | Number | The read on the encoder register available within the time period requested when the file was submitted to AquaCUE multiplied by the register resolution. |
| Read_Unit | 8 | Text | The unit of measurement for the reads. |
| Billing_Read | 9 | Number | The meter reading available within the time period requested when the file was submitted to AquaCUE used for billing purposes. |
| Read_Unit | 9 | Number | The unit of measurement for the reads. |
| Encoder_Read | 9 | Number | The reading on the encoder register available within the time period requested when the file was submitted to AquaCUE. |
| Read_Time | 22 | YYYY-MM-DD hh:mm:ss | Date and time of the read. (2014-09-10 10:39:41) |
| Service_Point_Timezone | 64 | Text | Name of the timezone where the service/meter is located, e.g. US/Pacific. If no timezone was provided, the timezone associated with the facility in AquaCUE will be used. |
| Tamper_Code | 7 | Text | A code that represents an endpoint condition such as potential leak (L), no usage (U), reverse flow (R), or cut wire (T). |
HTTP Status Codes
| Code | Description |
| 202 Accepted | Request accepted and there should be some content, assume the operation is in progress. |
| 400 Bad Request | Badly formatted request. |
| 401 Unauthorized | No Authorization header, or not authorized. |
| 403 Forbidden | User does not have permission. |
| 404 Not Found | Returned when an internal resource isn’t found. |
Objects
Pagination
JSON results that are paginated are returned in a pagination wrapper object, with the actual objects under a results property.
| property | type | description |
| total | int | The total number in the set. |
| from | int | The first record number of the set in these results. Starting at 1. |
| to | int | The last record number of the set in these results. Starting at 1. |
| results | object array | An array of the result objects–see API for type of object. |
EDSNew
Objects Created at the time of a new EDS request.
| property | type | description |
| edsUUID | UUID | UUID of EDS request. |
| statusURL | URL | URL to check on status of EDS execution. |
EDSStatus
Calls that return status of an EDS request.
| property | type | description |
| startTime | date | Date that processing began. |
| endTime | date | Date that processing stopped. |
| queueTime | date | Date of upload. |
| state | enum | Current state of a EDS {queue, run, exception, done}. |
| message | string | Human readable message describing state. |
| progress | Progress | Current progress. |
| reportUrl | URL | On completion of processing – where to find the exported data. |
Progress
propertytypedescription
| percentComplete | float | Current progress. |
| ETA | date | Estimated date of completion. |
| message | string | Description of current work. |
Export Data Services API Process Diagram
| Last Update | What Changed | What You Need to Do |
| December 22, 2020-Version 1.5.2 | Added includeReads, syncRegisters and syncTolerance parameters to /v1/eds/read. | Use the new parameters as needed. |
| October 16, 2019-Version 1.5.1 | Added the csvSeparator parameter to specify the desired column separator. | If desired, use the new parameter to specify one of semicolon (;), colon (:), pipe (|) or tilda (~). If not specified, a comma (,) will be used as the column separator. |
| October 7, 2019-Version 1.5 | Added v1/eds/exception_range endpoint. | Call the new endpoint to retrive historical exception reports over a given date range. |
| May 28, 2019-Version 1.4.9 | Added Canadian URL notification. | Utilities that login to AquaCUE using aquacue.ca should change all API endpoint calls to api.beaconama.ca. |
| February 1, 2019-Version 1.4.9 | Deprecated the Offset parameter and replaced it with lastMeterID for paginating results. | Use the new lastMeterID parameter to paginate results as needed. |
| May 25, 2018-Version 1.4.8 | Added support for quoting options all and none to POST /eds/v1/flow, POST /eds/v1/consumption and POST /eds/v1/range. | If desired, use the new quoting options. |
| April 30, 2018-Version 1.4.7 | Added support for the Num_Meter headerColumn to POST /eds/v1/consumption. When included, Num_Meters counts the number of meters with >0 flow. | If desired, use the new headerColumn. |
| November 13, 2017-Version 1.4.6 | Tolerance is no longer required for POST /EDS/v1/Reads. If not provided, EDS returns the last read available for each meter. | No action required. |
| November 2, 2017-Version 1.4.5 | Expanded the list of supported Resolutions to include Quarter_Hourly (15 minute interval reads). | If you use ORION Cellular LTE endpoints, you can now export quarter hourly interval reads. |
| October 4, 2017-Version 1.4.4 | Added documentation for /v1/eds/consumption/. Removed support for raw output. | Use the v1 consumption endpoint as needed. |
| September 26, 2016-Version 1.4.3 | Expanded the number of meters from 10,000 to 25,000 per export call. | Expand your export calls and successive export offsets accordingly. |
| July 27, 2016-Version 1.4.2 | Added hasEndpoint, meterSize and servicePointClassCode parameters and expanded the list of supported columnHeaders. | Use the new parameters and columnHeaders as needed. |
| June 30, 2016-Version 1.4.1 | Revised the Read CSV Export Format definition to include column headers. | Add column headers to your Read CSV Exports as needed. |
| April 12, 2016-Version 1.4 | This extensive update addressed facility requests by adding support for multiple new export options: flow, date range, reads selected by filter, export of column headers. | Revise your API code based on this extensive update. |
| March 23, 2016-Version 1.3 | Added support for billing read export in Badger Meter Read Center Format C. | Append your code if this function is important to you. |
| February 29, 2016-Version 1.2 | Added raw and display output formats to enhance viewing compatibility with billing and spreadsheet programs. | Append your code if this function is important to you. |
| February 19, 2016-Version 1.1 | Added support for specifying the column headers included in exports. | Append your code if this function is important to you. |
| February 12, 2016-Version 1.0 | New URL for accessing our API endpoints. | Update the URLs in your code per the documentation. |
