Export Data Services API v2

(Last updated April 21, 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.

/v2/eds/consumption

Method Description
Post Post a request to export aggregated total consumption.

/v2/eds/range

Method Description
POST Post a request to export flow data within a date range.

/v2/eds/flow

Method Description
POST Post a request to export aggregate flow data and reads at a start and end date.

/v2/eds/formatC

Method Description
POST Post a request to export the latest billing read data using Format C input files.

/v2/eds/leak

Method Description
POST Post a request to export a list of meters with leaks, the leak start date and the current leak rate.

/v2/eds/read

Method Description
POST Post a request to export the latest billing read data.

/v2/eds/exception_range

Method Description
POST Post a request to export a list of alerts from meters, encoders and endpoints along with alert start and end dates.

/eds/v1/status/{edsUUID}

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 (error) 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 (error) Text List of column names to include in the output:

Day_of_Week
Flow
Flow_Time
Flow_Unit
Num_Meters

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:

  • all: quote all fields.
  • none: exclude quotes.

For more on using quotes click here.

Resolution Text Aggregation level:

  • Daily (default)
  • Quarter_Hourly
  • Hourly
  • Monthly
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 (error) 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
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

POST EDS::Request

POST /v2/eds/consumption


# 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
#

curl

# 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
#

POST EDS::Response

{
"edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
"statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

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 (error) 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
Account_Email
Account_First_Name
Account_Full_Name
Account_ID
Account_Last_Name
Account_Phone
Account_Portal_Status
Account_Status
Alert_Code
Backflow_Gallons
Battery_Level
Billing_Address_Line1
Billing_Address_Line2
Billing_Address_Line3
Billing_City
Billing_Country
Billing_State
Billing_Zip
Connector_Type
Current_Leak_Rate
Current_Leak_Start_Date
Demand_Zone_ID
Dials
Endpoint_Install_Date
Endpoint_SN
Endpoint_Status
Endpoint_Type
Estimated_Flag
Flow
Flow_Time
Flow_Unit
High_Read_Limit
Last_Comm_Time
Location_Address_Line1
Location_Address_Line2
Location_Address_Line3
Location_Address_Parity
Location_Area
Location_Bathrooms
Location_Building_Number
Location_Building_Type
Location_City
Location_Continuous_Flow
Location_Country
Location_County_Name
Location_DHS_Code
Location_District
Location_Funding
Location_ID
Location_Irrigated_Area
Location_Irrigation
Location_Latitude
Location_Longitude
Location_Main_Use
Location_Name
Location_Pool
Location_Population
Location_Site
Location_State
Location_Water_Type
Location_Year_Built
Location_Zip
Low_Read_Limit
Meter_Continuous_Flow
Meter_ID
Meter_Install_Date
Meter_Manufacturer
Meter_Model
Meter_Note
Meter_Size
Meter_Size_Desc
Meter_Size_Unit
Meter_SN
Person_ID
Portal_ID
Read
Read_Code_1
Read_Code_2
Read_Code_3
Read_Method
Read_Note
Read_Sequence
Read_Time
Read_Time
Read_Unit
Reader_Initials
Register_Note
Register_Number
Register_Resolution
Register_Unit_Of_Measure
SA_Start_Date
Service_Point_Class_Code
Service_Point_Class_Code_Normalized
Service_Point_Cycle
Service_Point_ID
Service_Point_Latitude
Service_Point_Longitude
Service_Point_Route
Service_Point_Timezone
Service_Point_Type
Signal_Strength
Supply_Zone_ID
Trouble_Code
Utility_Use_1
Utility_Use_2


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
Meter_Temp_Min
Meter_Temp_Average
Water_Pressure_Max
Water_Pressure_Min
Water_Pressure_Average
Water_Temp_Max
Water_Temp_Min
Water_Temp_Average
Endpoint_Temp_Max
Endpoint_Temp_Min
Endpoint_Temp_Average

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:

  • all: quote all fields.
  • none: exclude quotes.

For more on using quotes click here.

Resolution Text Aggregation level:

  • Daily (default)
  • Quarter_Hourly
  • Hourly
  • Monthly
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 (error) 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
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

 

POST EDS::Request

POST /v2/eds/range

# 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 \
#

curl


# 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
#

Response

{
"edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
"statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

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 (error) 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
Account_Email
Account_First_Name
Account_Full_Name
Account_ID
Account_Last_Name
Account_Phone
Account_Portal_Status
Account_Status
Alert_Code
Backflow_Gallons
Battery_Level
Billing_Address_Line1
Billing_Address_Line2
Billing_Address_Line3
Billing_City
Billing_Country
Billing_State
Billing_Zip
Connector_Type
Current_Leak_Rate
Current_Leak_Start_Date
Dials
Endpoint_Install_Date
Endpoint_SN
Endpoint_Status
Endpoint_Type
Flow
Flow_Unit
High_Read_Limit
Last_Comm_Time
Location_Address_Line1
Location_Address_Line2
Location_Address_Line3
Location_Address_Parity
Location_Area
Location_Bathrooms
Location_Building_Number
Location_Building_Type
Location_City
Location_Continuous_Flow
Location_Country
Location_County_Name
Location_DHS_Code
Location_District
Location_Funding
Location_ID
Location_Irrigated_Area
Location_Irrigation
Location_Latitude
Location_Longitude
Location_Main_Use
Location_Name
Location_Pool
Location_Population
Location_Site
Location_State
Location_Water_Type
Location_Year_Built
Location_Zip
Low_Read_Limit
Meter_Continuous_Flow
Meter_ID
Meter_Install_Date
Meter_Manufacturer
Meter_Model
Meter_Note
Meter_Size
Meter_Size_Desc
Meter_Size_Unit
Meter_SN
Person_ID
Point_1_Read
Point_1_Read_Time
Point_2_Read
Point_2_Read_Time
Portal_ID
Read_Unit
Register_Number
Register_Resolution
Register_Unit_Of_Measure
SA_Start_Date
Service_Point_Class_Code
Service_Point_Class_Code_Normalized
Service_Point_Cycle
Service_Point_ID
Service_Point_Latitude
Service_Point_Longitude
Service_Point_Route
Service_Point_Timezone
Service_Point_Type
Signal_Strength
Utility_Use_1
Utility_Use_2


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
Meter_Temp_Min
Meter_Temp_Average
Water_Pressure_Max
Water_Pressure_Min
Water_Pressure_Average
Water_Temp_Max
Water_Temp_Min
Water_Temp_Average
Endpoint_Temp_Max
Endpoint_Temp_Min
Endpoint_Temp_Average

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:

  • all: quote all fields.
  • none: exclude quotes.

For more on using quotes click here.

Resolution Text Aggregation level:

  • Daily (default)
  • Quarter_Hourly
  • Hourly
  • Monthly
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 (error) 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
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

POST /eds/v2/flow

# 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
#

curl

# 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
#

POST EDS::Response

{
"edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
"statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

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 (error) File The input file in Format C from which to extract the meter and account information.
Date (error) 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 (error) Number How many hours to look backward for the latest reading. Must be >= 6.

POST /v2/eds/formatc

# 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
#

curl

# 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
#

POST EDS::Response

{
"edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
"statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

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
Account_Email
Account_First_Name
Account_Full_Name
Account_ID
Account_Last_Name
Account_Phone
Account_Portal_Status
Account_Status
Alert_Code
Backflow_Gallons
Battery_Level
Billing_Address_Line1
Billing_Address_Line2
Billing_Address_Line3
Billing_City
Billing_Country
Billing_State
Billing_Zip
Connector_Type
Current_Leak_Rate
Current_Leak_Start_Date
Dials
Endpoint_Install_Date
Endpoint_SN
Endpoint_Status
Endpoint_Type
High_Read_Limit
Last_Comm_Time
Location_Address_Line1
Location_Address_Line2
Location_Address_Line3
Location_Address_Parity
Location_Area
Location_Bathrooms
Location_Building_Number
Location_Building_Type
Location_City
Location_Country
Location_County_Name
Location_DHS_Code
Location_District
Location_Funding
Location_ID
Location_Irrigated_Area
Location_Irrigation
Location_Latitude
Location_Longitude
Location_Main_Use
Location_Name
Location_Pool
Location_Population
Location_Site
Location_State
Location_Water_Type
Location_Year_Built
Location_Zip
Low_Read_Limit
Meter_Continuous_Flow
Meter_ID
Meter_Install_Date
Meter_Manufacturer
Meter_Model
Meter_Note
Meter_SN
Meter_Size
Meter_Size_Desc
Meter_Size_Unit
Person_ID
Portal_ID
Register_Number
Register_Resolution
Register_Unit_Of_Measure
SA_Start_Date
Service_Point_Class_Code
Service_Point_Class_Code_Normalized
Service_Point_Cycle
Service_Point_ID
Service_Point_Latitude
Service_Point_Longitude
Service_Point_Route
Service_Point_Timezone
Service_Point_Type
Signal_Strength
Utility_Use_1
Utility_Use_2


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
Meter_Temp_Min
Meter_Temp_Average
Water_Pressure_Max
Water_Pressure_Min
Water_Pressure_Average
Water_Temp_Max
Water_Temp_Min
Water_Temp_Average
Endpoint_Temp_Max
Endpoint_Temp_Min
Endpoint_Temp_Average

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:

  • all: quote all fields.
  • none: exclude quotes.

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


# 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
#

curl

# 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
#

POST EDS::Response

{
"edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
"statusUrl": "/v2/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

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 (error) 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
Account_Email
Account_First_Name
Account_Full_Name
Account_ID
Account_Last_Name
Account_Phone
Account_Portal_Status
Account_Status
Alert_Code
Backflow_Gallons
Battery_Level
Billing_Address_Line1
Billing_Address_Line2
Billing_Address_Line3
Billing_City
Billing_Country
Billing_Read
Billing_Read_Unit
Billing_State
Billing_Zip
Connector_Type
Current_Leak_Rate
Current_Leak_Start_Date
Demand_Zone_ID
Dials
Encoder_Read
Endpoint_Install_Date
Endpoint_SN
Endpoint_Status
Endpoint_Type
High_Read_Limit
Last_Comm_Time
Location_Address_Line1
Location_Address_Line2
Location_Address_Line3
Location_Address_Parity
Location_Area
Location_Bathrooms
Location_Building_Number
Location_Building_Type
Location_City
Location_Continuous_Flow
Location_Country
Location_County_Name
Location_DHS_Code
Location_District
Location_Funding
Location_ID
Location_Irrigated_Area
Location_Irrigation
Location_Latitude
Location_Longitude
Location_Main_Use
Location_Name
Location_Pool
Location_Population
Location_Site
Location_State
Location_Water_Type
Location_Year_Built
Location_Zip
Low_Read_Limit
Meter_Continuous_Flow
Meter_ID
Meter_Install_Date
Meter_Manufacturer
Meter_Model
Meter_Note
Meter_Size
Meter_Size_Desc
Meter_Size_Unit
Meter_SN
Person_ID
Portal_ID
Read
Read_Code_1
Read_Code_2
Read_Code_3
Read_Method
Read_Note
Read_Sequence
Read_Time
Read_Unit
Reader_Initials
Register_Note
Register_Number
Register_Resolution
Register_Unit_Of_Measure
SA_Start_Date
Service_Point_Class_Code
Service_Point_Class_Code_Normalized
Service_Point_Cycle
Service_Point_ID
Service_Point_Latitude
Service_Point_Longitude
Service_Point_Route
Service_Point_Timezone
Service_Point_Type
Signal_Strength
Tamper_Code
Trouble_Code
Utility_Use_1
Utility_Use_2


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
Meter_Temp_Min
Meter_Temp_Average
Water_Pressure_Max
Water_Pressure_Min
Water_Pressure_Average
Water_Temp_Max
Water_Temp_Min
Water_Temp_Average
Endpoint_Temp_Max
Endpoint_Temp_Min
Endpoint_Temp_Average

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:

  • all: quote all fields.
  • none: exclude quotes.

For more on using quotes click here.

Resolution Text Aggregation level:

  • Daily (default)
  • Quarter_Hourly
  • Hourly
  • Monthly
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.
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
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

 

POST EDS::Request

POST /v2/eds/read

# 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
#

curl

# 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
#

POST EDS::Response

{
"edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
"statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

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 (error) 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
Meter_Temp_Min
Meter_Temp_Average
Water_Pressure_Max
Water_Pressure_Min
Water_Pressure_Average
Water_Temp_Max
Water_Temp_Min
Water_Temp_Average
Endpoint_Temp_Max
Endpoint_Temp_Min
Endpoint_Temp_Average

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:

  • csv: produces simple CSV files with quoted strings when needed (default)
  • json: produces JSON for use by other programs
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 (error) 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

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

curl

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

POST EDS::Response

{
"edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
"statusUrl": "/v2/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

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 (error) UUID An identifier for the request.

GET EDS::Request

# # Use this command to retrieve the latest
# billing read export status.
#
GET /v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034
#

curl

# 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
#

GET EDS status::Response::Queued

{
"state": "queue",
"message": "Export operation queued for processing.",
"queueTime": "2015-01-14T23:50:59Z"
}

GET EDS status::Response::Running

{
"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"
}

GET EDS status::Response::Exception

{
"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"
}

GET EDS status::Response::Complete

{
"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/. . ."
}

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
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 /eds/v2/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 /eds/v2/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 /eds/v2/reads. 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.
KNOWLEDGE BASE



User Guide