Export Data Service API v1

(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.

/v1/eds/flow

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

/v1/eds/consumption

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

/v1/eds/formatc

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

/v1/eds/range

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

/v1/eds/read

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


/v1/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.

/v1/eds/status{edsUUID}

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 (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.

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
• Endpoint_SN
• Flow
• Flow_Unit
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Pool
• Location_Population
• Location_Site
• Location_Water_Type
• Location_Year_Built
• Meter_ID
• Point_1_Read
• Point_1_Read_Time
• Point_2_Read
• Point_2_Read_Time
• Portal_ID
• Read_Unit
• Register_Number
• Service_Point_ID
• Service_Point_Timezone

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:

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

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 (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.

unit Text Unit in which to present flow data:

• acrefeet
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

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 (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.

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 (error) Text Comma-separated 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.
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:

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

For more on using quotes click here.

resolution Text Aggregation level:

  • daily (default)
  • quarter_hourly
  • hourly
  • monthly
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 (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 >= 24.
unit Text Unit in which to present flow data:

• acrefeet
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

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 (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 >= 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 (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

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
• Account_ID
• Backflow (gal/30 days)
• Battery Level
• Billing_Address_Line1
• Billing_Address_Line2
• Billing_Address_Line3
• Billing_City
• Billing_State
• Billing_Zip
• Connector Type
• Current Leak Rate (gal/hr)
• Current Leak Start Date
• Dials
• Encoder_Read
• Endpoint Status
• Endpoint_SN
• Endpoint_Type
• Estimated Flag
• Flow
• Flow_Time
• Flow_Unit
• Last Comm. Time
• Last Gateway Id
• Location_Address_Line1
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_City
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Name
• Location_Pool
• Location_Population
• Location_Site
• Location_State
• Location_Water_Type
• Location_Year_Built
• Location_Zip
• Meter_ID
• Meter_Manufacturer
• Meter_Model
• Meter_SN
• Meter_Size
• Meter_Size_Desc
• Portal_Email
• Portal_ID
• Read
• Read_Method
• Read_Time
• Read_Unit
• Register_Number
• Register_Resolution
• Register_Unit_Of_Measure
• Service_Point_Class_Code
• Service_Point_Cycle
• Service_Point_ID
• Service_Point_Latitude
• Service_Point_Longitude
• Service_Point_Route
• Service_Point_Timezone
• Signal Strength

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:

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

For more on using quotes click here.

resolution Text Aggregation level:

• daily (default)
• quarter_hourly
• hourly
• monthly

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 (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.

unit Text Unit in which to present flow data:

• acrefeet
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

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 (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.

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
• Billing_Read
• Billing_Read_Unit
• Encoder_Read
• Endpoint_SN
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Pool
• Location_Population
• Location_Site
• Location_Water_Type
• Location_Year_Built
• Meter_ID
• Portal_Email
• Portal_ID
• Read
• Read_Method
• Read_Time
• Read_Unit
• Register_Number
• Service_Point_ID
• Service_Point_Timezone
• Tamper_Code

includeReads 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 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:

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

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

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:

  • 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
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:

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

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 (error) 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
• Billing_Read
• Billing_Read_Unit
• Encoder_Read
• Endpoint_SN
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Pool
• Location_Population
• Location_Site
• Location_Water_Type
• Location_Year_Built
• Meter_ID
• Portal_Email
• Portal_ID
• Read
• Read_Method
• Read_Time
• Read_Unit
• Register_Number
• Service_Point_ID
• Service_Point_Timezone
• Tamper_Code

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.
KNOWLEDGE BASE



User Guide