Export Data Service v1 API

(Last updated April 15, 2024)

NOTE TO BEACON API USERS IN CANADA

In compliance with Canadian cross-border data regulations, your utility data is or already has been moved to Canada. As a result, if you login to BEACON 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 utilities 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 interval meter reads and 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.

BEACON 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 BEACON 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 BEACON Monitor.
continuousFlowExpected		Text	Yes/No.
dhsCode		Text	Department of Health Services code used to identify water sources.
district		Text	A unique identifier for the district.
endDate		Date	Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided.
funding		Text	Label for filtering in BEACON 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 BEACON 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 BEACON Monitor.
startDate		Date	Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided.
unit		Text	Unit in which to present flow data: • acrefeet • ccf • cubicfeet • cubicmeter • gallons (default) • liter • meterunit Meterunit returns results in the the meter’s unit of measure.
waterType		Text	Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON Monitor.

POST EDS::Request

POST /v1/eds/flow

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

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

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.

POST /v1/eds/consumption

Submits a request to retrieve aggregated consumption data at a start and end date.

Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.

Parameters:

Parameter Name	Required	Type	Description
endDate		Date	Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided.
hasEndpoint		Boolean	true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both.
headerColumns		Text	Comma-separated list of column names to include in the output: Day_of_Week 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 BEACON 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 BEACON Monitor.
mainUse		Text	Label for filtering in BEACON Monitor.
site		Text	Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in BEACON Monitor.
waterType		Text	Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON 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		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

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

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

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 /v1/eds/formatc

Post a request to export the latest billing read data using a Format C input file within the given tolerance. This API endpoint uses the meter and account information from the given file as its filters. The returned data will be in Format C, per the original file, rather than in CSV format.

Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.

Parameters:

Parameter Name	Required	Type	Description
data		File	The input file in Format C from which to extract the meter and account information.
date		Date	Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided.
tolerance		Number	How many hours to look backward for the latest reading. Must be >= 24.

POST EDS::Request

POST /v1/eds/formatc

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

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 /v1/eds/range

Submits a request to export interval meter reads and 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 BEACON Monitor.
continuousFlowExpected		Text	Yes/No.
dhsCode		Text	Department of Health Services code used to identify water sources.
district		Text	A unique identifier for the district.
endDate		Date	Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided
funding		Text	Label for filtering in BEACON 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 Per Day • 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 BEACON 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 BEACON Monitor.
startDate		Date	Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided.
unit		Text	Unit in which to present flow data: • acrefeet • ccf • cubicfeet • cubicmeter • gallons (default) • liter • meterunit Meterunit returns results in the the meter’s unit of measure.
waterType		Text	Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON Monitor.

POST EDS::Request

POST /v1/eds/range

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

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

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 /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 BEACON Monitor.
continuousFlowExpected		Text	Yes/No.
date		Date	Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided.
dhsCode		Text	Department of Health Services code used to identify water sources.
district		Text	A unique identifier for the district.
funding		Text	Label for filtering in BEACON 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 BEACON 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 BEACON Monitor.
syncTolerance		Number	How many minutes to look backward for the latest reading. If not provided, defaults to 1440 minutes (24 hours).
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 BEACON Monitor.

POST EDS::Request

POST /v1/eds/read

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

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

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.

POST /v1/eds/exception_range

Submits a request to retrieve a report of historical exceptions

Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.

Parameters:

Parameter Name	Required	Type	Description
buildingType		Text	Optional building type (eg, ‘retail’, ‘dining’, ‘apartments’) label
continuousFlowExpected		Text	Yes/No
dhsCode		Text	Optional Department of Health Services code
district		Text	A unique identifier for the district
endDate		Date	Date requested; string quoted ISO 8601, e.g. “`2015-08-23T22:06:09Z`“. The code will default to 23:59:59 in the meter’s timezone if the time component is not provided
funding		Text	Optional funding label
hasEndpoint		Boolean	`true` to limit results to meters that have an endpoint, `false` for meters that have no endpoint, or omit to include both
headerColumns		Text	Comma-separated list of column names to include in the output: 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		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

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

curl

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

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

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

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

CSV Export Formats

Flow CSV Export Formats

This CSV file format definition describes the billing read output of BEACON. 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 BEACON. 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 BEACON 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 BEACON 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 BEACON.
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 BEACON 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.

BEACON Export Data Services API Process Diagram

Last Update	What Changed	What You Need to Do
April 15, 2024	Updated the following columnHeaders for eds/v1/range: Current Leak Start Date, Current Leak Rate Per Day	Adjust your API calls accordingly.
June 6, 2023	Due to a security enhancement, removed the / in the Note to BEACON API Users in Canada section.	Adjust your API calls accordingly.
November 11, 2022-Version 1.5.5	Deprecated the syncTolerance parameter for /v1/eds/reads. Changed the sync_Tolerance default to 1440 minutes.	Adjust your API calls accordingly.
May 24, 2021-Version 1.5.4	Added support for meterunit in the Unit parameter for /v1/eds/flow and /v1/eds/range.	Use meterunit as needed.
December 22, 2020-Version 1.5.3	Added includeReads parameter to /v1/eds/read.	Use the new parameter as needed.
November 30, 2020-Version 1.5.2	Added 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 BEACON using beaconama.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 utility 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.