(Last updated June 6, 2023)
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.
EDS v2 gives utilities 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 flow and billing read exports with tamper codes.)
- Retrieve export results using GET /v1/eds/status/{edsUUID}.
EDS API v2 Overview
The BEACON EDS API v2 provides the following methods to support data export functionality.
| Method | Description |
| Post | Post a request to export aggregated total consumption. |
| Method | Description |
| POST | Post a request to export interval meter reads and flow data within a date range. |
| Method | Description |
| POST | Post a request to export aggregate flow data and reads at a start and end date. |
| Method | Description |
| POST | Post a request to export the latest billing read data using Format C input files. |
| Method | Description |
| POST | Post a request to export a list of meters with leaks, the leak start date and the current leak rate. |
| Method | Description |
| POST | Post a request to export the latest billing read data. |
| Method | Description |
| POST | Post a request to export a list of alerts from meters, encoders and endpoints along with alert start and end dates. |
| Method | Description |
| GET | Retrieves the current status of the export processing, including a URL to download the export results, when available. |
Authentication
Authentication is basic authentication, in which the caller needs a valid BEACON username and password. In addition, API access must be enabled for the utility.
v2 BEACON Export Data Services API
POST /v2/eds/consumption
Submits a request to retrieve aggregated consumption data at a start and end date.
Note: The Content-Type header should be set to application/x-www-form-urlencoded in the request.
Parameters:
| Parameter Name | Required | Type | Description |
| End_Date |  |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | |
Text | List of column names to include in the output:
Day_of_Week Num_Meters counts the total number of meters with >0 flow. |
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in BEACON 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 BEACON Monitor. | |
| Location_Main_Use | Text | Label for filtering in BEACON Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in BEACON Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Start_Date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Unit | Text | Unit in which to present flow data:
• acrefeet |
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 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 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 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 |
| End_Date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | Text | List of column names to include in the output:
Account_Billing_Cycle Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in BEACON 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 BEACON Monitor. | |
| Location_Main_Use | Text | Label for filtering in BEACON Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in BEACON Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. When using multiple Meter_IDs we recommend sending the request via the POST body and not as query-string. This avoids quickly reaching the URL length limit and having the call rejected. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Start_Date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”,.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Unit | Text | Unit in which to present flow data:
• acrefeet Meterunit returns results in the the meter’s unit of measure. |
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 \ 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 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 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 |
| End_Date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | Text | List of column names to include in the output:
Account_Billing_Cycle Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in BEACON 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 BEACON Monitor. | |
| Location_Main_Use | Text | Label for filtering in BEACON Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in BEACON Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Start_Date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Unit | Text | Unit in which to present flow data:
• acrefeet Meterunit returns results in the the meter’s unit of measure. |
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 | |
File | The input file in Format C from which to extract the meter and account information. |
| Date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Tolerance | |
Number | How many hours to look backward for the latest reading. Must be >= 6. |
POST /v2/eds/formatc
# 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 | |
| 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 BEACON 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 BEACON Monitor. | |
| Location_Main_Use | Text | Label for filtering in BEACON Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in BEACON Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. |
POST EDS::Request
POST /v2/eds/leak
# 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 | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z”.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided. |
| Has_Endpoint | Boolean | true to limit results to meters that have an endpoint, false for meters that have no endpoint, or omit to include both. | |
| Header_Columns | Text | List of column names to include in the output:
Account_Billing_Cycle Use the following Column_Headers to return sensor data from Badger Meter E-Series Ultrasonic meters with water pressure and temperature sensing capability that are connected to ORION Cellular LTE or LTE-M endpoints. Meter_Temp_Max |
|
| Include_Reads | Text | Export records for all meters, meters with or meters without current billing reads. If not provided, defaults to all.
Enter one of: Current billing reads = a billing read that falls within the given tolerance setting. If the current read = previous read or if the current read = 0, then the read will be returned. |
|
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 25000. Must be between 1 and 25000. | |
| Location_Building_Type | Text | Label (e.g. ‘retail,’ ‘dining,’ apartments’) used for filtering in BEACON 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 BEACON Monitor. | |
| Location_Main_Use | Text | Label for filtering in BEACON Monitor. | |
| Location_Site | Text | Label (e.g. ‘North Campus,’ ‘Uptown Village’) for filtering in BEACON Monitor. | |
| Location_Water_Type | Text | Label (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) for filtering in BEACON Monitor. | |
| Meter_Continuous_Flow | Text | Yes/No. | |
| Meter_ID | Text | An identifier for the meter; can be provided multiple times. | |
| Meter_Size | Text | Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) |
|
| Last_Meter_ID | Text | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
• csv: produces simple CSV files with quoted strings when needed (default). • json: produces JSON for use by other programs. |
|
| CSV_Separator | Text | Column separator to use. Enter one of:
, ; : | ~ E.g. a single character for comma (,), semicolon (;), colon (:), pipe (|) or tilda (~). |
|
| CSV_Quoting_Option | Text | Include or exclude quotes around all exported fields in a CSV file:
For more on using quotes click here. |
|
| Resolution | Text | Aggregation level:
|
|
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
| Service_Point_Cycle | Text | An identifier used to denote the billing cycle name. | |
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to. | |
| Sync_Tolerance | 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 >= 6. If not provided, EDS returns the last read available for each meter. | |
| Unit | Text | Unit in which to present flow data:
• acrefeet |
POST EDS::Request
POST /v2/eds/read
# 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 | |
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 | List of column names to include in the output:
| |
| Limit | Number | Limit the number of meters for which data is returned; used for pagination. Defaults to 10000. Must be between 1 and 10000 | |
| Location_Main_Use | Text | Optional main use label | |
|
Meter_ID |
Text |
An identifier for the meter; can be provided multiple times |
|
| Meter_Size | Text | Numeric size of the meter (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.) | |
| Last_Meter_ID | Number | Optional identifier used for pagination of meter results. | |
| Output_Format | Text | Output format to use:
|
|
| Service_Point_Route | Text | Identifier of the route or book the metered service belongs to | |
| Service_Point_Class_Code | Text | Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc. | |
|
Service_Point_Cycle |
Text |
An identifier used to denote the billing cycle name |
|
| Location_Site | Text | Optional site (eg, ‘North Campus’, ‘Uptown Village’) label | |
| Start_Date | |
Date | Date requested; string quoted ISO 8601, e.g. “2015-08-23T22:06:09Z“.
The code will default to 23:59:59 in the meter’s timezone if the time component is not provided |
| Location_Water_Type | Text | Optional water type (eg, ‘hot’, ‘cold’, ‘potable’, ‘reclaimed’) label |
POST EDS::Request
POST /v2/eds/exception_range
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 | |
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 |
| June 6, 2023 | Due to a security enhancement, removed the / in the Note to BEACON API Users in Canada section. | Modify your API calls accordingly. |
| March 24, 2023-Version 1.4.5 | Added Current_Leak_Unit, Demand_Zone_ID, Supply_Zone_ID to the list of available headers in the exception_range, range, read, flow, and leak APIs. Added Location_Address_Line1 to the list of available headers in the flow API. | Use the new headers as needed. |
| November 11, 2022-Version 1.4.4 | Deprecated the Sync_Registers boolean function for /v2/eds/reads. Changed the Sync_Tolerance default to 1440 minutes. | Adjust your API calls accordingly. |
| May 24, 2021-Version 1.4.3 | Added support for meterunit to the Unit parameter of /v2/eds/range and /v2/eds/flow. | Use meterunit as needed. |
| December 22, 2020-Version 1.4.2 | Added Include_Reads parameter to /v2/eds/read. | Use the new parameter as needed. |
| November 30, 2020-Version 1.4.1 | Added Sync_Registers and Sync_Tolerance parameters to /v2/eds/read. | Use the new parameters as needed. |
| October 9, 2020-Version 1.4 | Revised the limit of the Tolerance parameter to reflect the ability to set Tolerance (how far back the system looks for reads) to >= 6 hours. | Use the new limit 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. | Utilities that login to BEACON using beaconama.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/read. If not provided, EDS returns the last read available for each meter. | No action required. |
| November 1, 2017-Version 0.3 | Expanded the list of supported Resolutions to include Quarter_Hourly (15 minute interval reads). | If you use ORION Cellular LTE endpoints, you can now export quarter hourly interval reads. |
| October 3, 2017-Version 0.2 | Corrected list of supported column headers for POST /v2/eds/leak. | Check your scripts against the new list of column headers. If you do not see a column header in the new list, remove it from your scripts. |
| August 22, 2017-Version 0.1 | Preview released. | Take advantage of the new features in v2. |
