(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 aquacue.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.
EDS v2 gives facilities more options for exporting data. Included are more header columns, more parameters and new endpoints that let you programmatically export consumption (including the total number of meters reporting >0 flow) and current leak data.
What you need to know about EDS v2:
- Parameter and column names are different than those of EDS v1.
- Columns are in a different order than those of EDS v1.
- Both EDS v1 and EDS v2 are active. (If you use both, be sure your parameter and column names align with the API endpoint being called.)
- If you are already using EDS v1, you do not need to make any changes.
- Pagination, export options and authentication are identical for EDS v1 and EDS v2. (Refer to this page for pagination and authentication details. See this page for descriptions of export formats.)
- Retrieve export results using GET /v1/eds/status/{edsUUID}.
EDS API v2 Overview
The EDS API v2 provides the following methods to support data export functionality.
| Method | Description |
| Post | Post a request to export aggregated total consumption. |
| Method | Description |
| POST | Post a request to export flow data within a date range. |
| 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 the latest billing read data using Format C input files. |
| Method | Description |
| POST | Post a request to export a list of meters with leaks, the leak start date and the current leak rate. |
| 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. |
Authentication
Authentication is basic authentication, in which the caller needs a valid AqauCUE username and password. In addition, API access must be enabled for the facility.
v2 Export Data Services API
POST /v2/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 |
| End_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. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | |
Text | 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. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AqauCUE Monitor. | |
| Location_DHS_Code | Text | Department of Health Services code used to identify water sources. | |
| Location_District | Text | A unique identifier for the district. | |
| Location_Funding | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Main_Use | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AqauCUE Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AqauCUE Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Start_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 >= 6. | |
| Unit | Text | Unit in which to present flow data:
• acrefeet |
POST EDS::Request
POST /v2/eds/consumption
[sourcecode lng=”bash”]
# Use these parameters to post a request to export aggregate
# consumption for a start and end date at a given tolerance.
#
Service_Point_Cycle=11111
Start_Date=2016-02-01T00:00:00Z
End_Date=2016-02-29T23:59:59Z
Tolerance=72
Header_Columns=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 Service_Point_Cyce=11111 \
-d Start_Date=2016-02-01T00:00:00Z \
-d End_Date=2016-02-29T23:59:59Z \
-d Tolerance=72 \
-d Header_Columns=Flow,Flow_Time,Flow_Unit \
https://api.beaconama.net/v2/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
POST /v2/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 |
| End_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. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | Text | List of column names to include in the output:
Account_Billing_Cycle Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AqauCUE Monitor. | |
| Location_DHS_Code | Text | Department of Health Services code used to identify water sources. | |
| Location_District | Text | A unique identifier for the district. | |
| Location_Funding | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Main_Use | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AqauCUE Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AqauCUE Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Start_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 >= 6. | |
| Unit | Text | Unit in which to present flow data:
• acrefeet |
POST EDS::Request
POST /v2/eds/range
[sourcecode lang=”bash”]
# Use these parameters to submit a request to export
# flow data within a date range.
Service_Point_Cycle=11111 \
Start_Date=2015-08-23T22:06:09Z \
End_Date=2015-12-31T22:06:09Z \
Tolerance=72 \
Header_Columns=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” \
-d Service_Point_Cycle=11111 \
-d Location_District=las \
-d Start_Date=2015-08-23 \
-d End_Date=2015-12-31T22:06:09Z \
-d Tolerance=72 \
-d Header_Columns=Account_ID,Meter_ID,Read \
https://api.beaconama.net/v2/eds/range
#
[/sourcecode]
Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034”
}
[/sourcecode]
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 /v2/eds/flow
Submits a request to retrieve the export aggregate flow data and reads at given date and tolerance. 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 |
| End_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. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | Text | List of column names to include in the output:
Account_Billing_Cycle Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AqauCUE Monitor. | |
| Location_DHS_Code | Text | Department of Health Services code used to identify water sources. | |
| Location_District | Text | A unique identifier for the district. | |
| Location_Funding | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Main_Use | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AqauCUE Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AqauCUE Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Start_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 >= 6. | |
| Unit | Text | Unit in which to present flow data:
• acrefeet |
POST /eds/v2/flow
[sourcecode lang=”bash”]
# Use these parameters to post a request to export aggregate
# flow data and reads at a start and end date.
#
Service_Point_Cycle=11111
Start_Date=2016-02-01T00:00:00Z
End_Date=2016-02-29T23:59:59Z
Header_Columns=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 Service_Point_Cycle=11111 \
-d Location_District=las \
-d Start_Date=2016-02-01T00:00:00Z \
-d End_Date=2016-02-29T23:59:59Z \
-d Header_Columns=Account_ID,Meter_ID,Flow \
https://api.beaconama.net/v2/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]
POST /v2/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 multipart/form-data 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 >= 6. |
POST /v2/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: multipart/form-data” \
-F Data=@$HOME/Desktop/my-format-c-data.txt \
-F Date=2015-08-23T22:06:09Z \
-F Tolerance=72 \
https://api.beaconama.net/v2/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 /v2/eds/leak
Post a request to export a list of meters with leaks, the leak start date and the current leak rate.
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
| Parameter Name | Required | Type | Description |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | Text | List of column names to include in the output:
Account_Billing_Cycle Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AqauCUE Monitor. | |
| Location_DHS_Code | Text | Department of Health Services code used to identify water sources. | |
| Location_District | Text | A unique identifier for the district. | |
| Location_Funding | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Main_Use | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AqauCUE Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AqauCUE Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. |
POST EDS::Request
POST /v2/eds/leak
[sourcecode lang=”bash”]
# Use these parameters to post a request to export data
# for meters with leaks at a start and end date.
#
Service_Point_Cycle=11111
Header_Columns=Account_ID,Meter_ID,Current_Leak_Start_Date,Current_Leak_Rate
#
[/sourcecode]
curl
[sourcecode lang=”bash”]
# Use this cURL statement to post a request to export a list of meters
# with leaks along with the leak start date and current leak rate.
#
curl -X POST -uusername:password \
-H “Content-Type: application/x-www-form-urlencoded” \
-d Service_Point_Cyce=11111 \
-d Header_Columns=Account_ID,Meter_ID,Current_Leak_Start_Date,Current_Leak_Rate \
https://api.beaconama.net/v2/eds/leak
#
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v2/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 /v2/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 |
| 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. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | Text | List of column names to include in the output:
Account_Billing_Cycle Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Include_Reads | Text | Export records for all meters, meters with or meters without current billing reads. If not provided, defaults to all. Enter one of: • all • with • without 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 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in AqauCUE Monitor. | |
| Location_DHS_Code | Text | Department of Health Services code used to identify water sources. | |
| Location_District | Text | A unique identifier for the district. | |
| Location_Funding | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Main_Use | Text | Label for filtering in AqauCUE Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in AqauCUE Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in AqauCUE Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Sync_Registers | 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. | |
| Sync_Tolerance | 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 >= 6. If not provided, EDS returns the last read available for each meter. | |
| Unit | Text | Unit in which to present flow data:
• acrefeet |
POST EDS::Request
POST /v2/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.
#
Meter_Id=abc123
Meter_Id=xyz789
Date=2015-08-23T22:06:09Z
Tolerance=72
Header_Columns=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” \
-d Meter_Id=abc123 \
-d Meter_Id=xyz789 \
-d Date=2015-12-31T22:06:09Z \
-d Tolerance=72 \
-d Header_Columns=Account_ID,Meter_ID,Read \
https://api.beaconama.net/v2/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.
- location header points to statusUrl
POST /v2/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 |
| Location_Building_Type | Text | Optional building type (eg, ‘retail’, ‘dining’, ‘apartments’) label | |
| Continuous_Flow_Expected | Text | Yes/No | |
| Location_DHS_Code | Text | Optional Department of Health Services code | |
| Location_District | Text |
A unique identifier for the district |
|
| End_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 |
| Location_Funding | Text | Optional funding label | |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both |
|
| Header_Columns | Text | Comma-separated list of column names to include in the output: Location_Name Register_Number Endpoint_SN Meter_ID Meter_SN Service_Point_Timezone Exception_Start_Date Exception_End_Date Exception Account_ID Location_ID Account_Full_Name Billing_Address_Line1 Billing_Address_Line2 Billing_Address_Line3 Billing_City Billing_State Billing_Zip Service_Point_ID Service_Point_Class_Code Service_Point_Route Service_Point_Cycle Meter_Manufacturer Meter_Model Register_Resolution Register_Unit_Of_Measure Meter_Size Meter_Size_Desc Dials Service_Point_Latitude Service_Point_Longitude Endpoint_Type Connector_Type Endpoint_Status Supply_Zone_ID Demand_Zone_ID Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 10000. Must be between 1 and 10000 | |
| Location_Main_Use | Text | Optional main use label | |
|
Meter_ID |
Text |
An identifier for the meter; can be provided multiple times |
|
| Meter_Size | Text | Numeric size of the meter (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) | |
| Last_Meter_ID | Number | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
|
|
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to | |
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
|
Service_Point_Cycle |
Text |
An identifier used to denote the billing cycle name |
|
| Location_Site | Text | Optional site (eg, ‘North Campus’, ‘Uptown Village’) label | |
| Start_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 |
| Location_Water_Type | Text | Optional water type (eg, ‘hot’, ‘cold’, ‘potable’, ‘reclaimed’) label |
POST EDS::Request
POST /v2/eds/exception_range
[sourcecode lang=”bash”]
Service_Point_Cycle=11111
Start_Date=2019-09-01T00:00:00Z
End_Date=2019-09-27T23:59:59Z
Header_Columns=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 Service_Point_Cycle=11111 \
-d Location_District=las \
-d Start_Date=2016-02-01T00:00:00Z \
-d End_Date=2016-02-29T23:59:59Z \
-d Header_Columns=Account_ID,Meter_ID,Exception_Start_Date,Exception_End_Date,Exception \
https://api.beaconama.net/v2/eds/exception_range
[/sourcecode]
POST EDS::Response
[sourcecode lang=”bash”]
{
“edsUUID”: “70FC1B71-F0C3-4950-885C-A635E7C4E034”,
“statusUrl”: “/v2/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.
See Export Date Service API v1 documentation for details on CSV exports, JSON objects and HTTP Status Codes.
| Last Update | What Changed | What You Need to Do |
| December 22, 2020-Version 1.4.1 | Added Include_Reads, Sync_Registers and Sync_Tolerance parameters to v2/eds/read. | Use the new parameters as needed. |
| October 13, 2020-Version 1.4 | Revised the minimum Tolerance value from >= 24 to >= 6 hours. | Use the new value as needed. |
| April 21, 2020-Version 1.3 | Added Column_Headers to EDS v2 Range, Flow, Leak Read and Exception Range that enable export of sensor data from Badger Meter E-Series Ultrasonic meters connected to ORION Cellular LTE or LTE-M endpoints. | Use the new Column_Headers as needed. |
| October 16, 2019-Version 1.2 | Added the CSV_Separator 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.1 | Added eds/v2/exception_range endpoint. | Make calls to the new endpoint to retrieve historical exception reports over a given date range. |
| August 9, 2019-Version 1.0 | Revised list of supported column headers to reflect the current implementation. Specifically, for Range added: Estimated_Flag, Flow_Time, Read_Code_1, Read_Code_2, Read_Code_3, Read_Method, Read_Note, Read_Sequence, Read_Time, Reader_Initials; removed Reader_Code. For Flow added: Point_1_Read, Point_1_Read_Time, Point_2_Read, Point_2_Read_Time; removed Demand_Zone_ID, Reader_Code, Read, Read_Time, Supply_Zone_ID, Trouble_Code. For Leak removed: Demand_Zone_ID, Flow, Flow_Unit, Location_Continuous_Flow, Read, Read_Time, Read_Unit, Reader_Code, Supply_Zone_ID, Trouble_Code. For Read added: Billing_Read, Billing_Read_Unit, Encoder_Read, Read_Code_1, Read_Code_2, Read_Code_3, Read_Method, Read_Note, Read_Sequence, Reader_Initials, Tamper_Code; removed Flow, Flow_Unit, Reader_Code, Supply_Zone_ID. | Adjust your API calls as needed. |
| May 28, 2019-Version 0.9 | Added Canadian URL notification. | Facilities that login to AqauCUE using aquacue.ca should change all API endpoint calls to api.beaconama.ca. |
| March 27, 2019-Version 0.9 | Added Reader_Code and Trouble_Code to the lists of Column Headers. | Use the new column headers as needed. |
| February 1, 2019-Version 0.8 | Deprecated the Offset parameter and replaced it with Last_Meter_ID for paginating results. | Use the new Last_Meter_ID parameter to paginate results as needed. |
| August 13, 2018-Version 0.7 | Revised the list of column heads for the Range, Leak and Read endpoints by replacing Point_1_Read, Point_1_Read_Time, Point_2_Read, Point_2_Read_Time with Read and Read_Time Header_Columns. | If desired, include the new Header_Columns in your exports. |
| July 16, 2018-Version 0.6 | Updated the lists of Header_Columns to include Demand_Zone_ID, Supply_Zone_ID and Tamper_Code. | If desired, include the new Header_Columns in your exports. |
| May 25, 2018-Version 0.5 | Added support for output quoting options all (the default) and none to POST /v2/eds/consumption, POST /v2/eds/range, POST /v2/eds/flow, POST /v2/eds/leak and POST /v2/eds/read. | If desired, use the new quoting options. |
| April 26, 2018-Version 0.4 | Added support for the Num_Meter Header_Column to POST /v2/eds/consumption. When included, Num_Meters counts the number of meters with >0 flow. | If desired, use the new Header_Column. |
| November 13, 2017-Version 0.3 | Tolerance is no longer required for POST /v2/eds/read. If not provided, EDS returns the last read available for each meter. | No action required. |
| November 1, 2017-Version 0.3 | 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 3, 2017-Version 0.2 | Corrected list of supported column headers for POST /v2/eds/leak. | Check your scripts against the new list of column headers. If you do not see a column header in the new list, remove it from your scripts. |
| August 22, 2017-Version 0.1 | Preview released. | Take advantage of the new features in v2. |
