Import API
The Badger Meter Data Exchange (BDE) import service is based on the Common Services API and processes various BEACON data files through a standard programming interface. Data Exchange is used to keep the BEACON hierarchy of accounts and services in sync with customer data by automating the data import process. Additionally, the import service provides support for entering meter reads into BEACON.
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.
API Overview
The Data Exchange Import API provides the following methods to support data exchange functionality.
/v1/bde/import
Method |
Description |
POST |
Create a new Badger Meter Data Exchange. |
PUT |
Accept Dry Run of BEACON Data Exchange. |
/v1/bde/import/{bdeUUID}
Method |
Description |
GET |
Gets the import status of an existing BDE data file. |
/v1/bde/import/{bdeUUID}/report
Method |
Description |
GET |
Gets the report for a BDE that has successfully completed. |
Authentication
HTTP basic access authentication provides your applications with secure access to all data available to your account. Using your BEACON username and password, you can use your programming library’s base64 method to create an HTTP Authorization header. For an explanation of this procedure, see: http://en.wikipedia.org/wiki/Basic_access_authentication.
Badger Meter Data Exchange
POST /v1/bde/import
Create a new import type BDE by submitting a file for a particular type of processing. By default this will initiate a dry run of the data ingestion, which will need to be accepted by issuing the correct PUT method after the processing has completed.
File upload as described in RFC 2388.
Note: Files must be 70MB or less.
param |
required |
type |
description |
data |
 |
CSV |
The CSV file to be processed. |
Examples:
POST BDE::Request
POST /v1/bde/import
curl
# Use this cURL statement to create a new import type BDE
# by submitting a file for a particular type of processing.
# By default a dry run that scans the file for errors is
# initiated. The import must be accepted by issuing the
# correct PUT method after processing is complete.
curl -uusername:password \
-F data=@filename.csv \
https://api.beaconama.net/v1/bde/import
#
POST BDE::Response
{
"bdeUUID": "12313",
"statusUrl": "/v1/bde/import/12313"
}
Response
Returns BDENew object.
202 Accepted – The BDE has been submitted successfully and the status can be followed at the statusUrl location.
- location header points to statusUrl
POST /v1/bde/import?dryRun=false
Skip the dry run validation of a BDE.
Variables:
param |
required |
data |
description |
dryRun |
|
boolean |
false to disable, true to enable. Defaults to true if not provided. |
data |
 |
CSV |
The CSV file to be processed. |
Examples:
POST BDE::Accept Import without Dry Run
POST /v1/bde/import?dryRun=false
curl
# Use this cURL query to disable the dry run process
# and accept a file for import. The exceptions report will still
# be available in the Assets>System Sync page Activity List.
curl -v "https://api.beaconama.net/v1/bde/import?dryRun=false" \
-F "data=@file_name.csv;type=text/csv" \
-u"username:password"
#
POST BDE::Response
{
"bdeUUID": "12313",
"statusUrl": "/v1/bde/import/12313"
}
PUT /v1/bde/import/{bdeUUID}
Accept the dry run of a BDE.
Variables:
param |
required |
type |
description |
bdeUUID |
 |
UUID |
The bdeType UUID to accept the dry run. |
Examples:
PUT BDE::Accept
PUT /v1/bde/import/12313
curl
# Use this cURL statement to accept a BDE dry run.
curl -uusername:password \
https://api.beaconama.net/v1/bde/import/12313
#
POST BDE::Response
{
"bdeUUID": "12313",
"statusUrl": "/v1/bde/import/12313"
}
Response
Returns BDENew object.
202 Accepted – The BDE has been submitted successfully and the status can be followed at the statusUrl location.
- location header points to statusUrl
GET /v1/bde/import/{bdeUUID}
Get the status of an existing BDE.
Variables:
param |
required |
type |
description |
bdeUUID |
 |
UUID |
The bdeType UUID to get the BDE status. |
Examples:
GET BDE status::Request
GET /v1/bde/import/12313
curl
# Use this cURL statement to get the status
# of an existing BDE file.
curl -uusername:password \
-F data=@filename.csv \
https://api.beaconama.net/v1/bde/import
#
GET BDE status::Response::Queued
{
"state": "queue",
"dryRun": true,
"message": "Provisioning Import operation queued for processing.",
"queueTime": "2015-01-14T23:50:59Z"
}
GET BDE status::Response::Running
{
"startTime": "2015-01-15T00:00:00Z",
"dryRun": true,
"state": "run",
"progress": {
"percentComplete": "12.0",
"ETA": "2015-01-15T01:02:31Z",
"message": "performing validation"
},
"message": "Import operation running.",
"queueTime": "2015-01-14T23:50:59Z"
}
GET BDE status::Response::Exception
{
"startTime": "2015-01-15T00:00:00Z",
"dryRun": true,
"state": "exception",
"endTime": "2015-01-15T01:02:30Z",
"message": "Import operation had problems.",
"queueTime": "2015-01-14T23:50:59Z"
}
GET BDE status::Response::Complete
{
"startTime": "2015-01-15T00:00:00Z",
"dryRun": true,
"state": "done",
"endTime": "2015-01-15T01:02:30Z",
"message": "Import operation succeeded.",
"queueTime": "2015-01-14T23:50:59Z",
"reportUrl": "/v1/bde/import/12313/report"
}
Response
Returns BDEStatus object.
GET /v1/bde/import/{bdeUUID}/report
Get report generated after the BDE has been processed.
Variables:
param |
required |
type |
description |
bdeUUID |
 |
UUID |
The bdeType UUID to get the report. |
Examples:
GET BDE report::Request
GET /v1/bde/import/12313/report
curl
# Use this cURL statement to get the report that
# was generated after the BDE has been processed.
curl -uusername:password \
https://api.beaconama.net/v1/bde/import/12313/report
#
GET BDE report::Response
{
"dryRun": false,
"ok": 104,
"error": 23,
"originalUrl": "/v1/content/import/12313/import.csv",
"errorUrl": "/v1/content/import/12313/errors.json",
"errorSheetUrl": "/v1/content/import/12313/errors.csv",
}
Response
Returns BDEReport object.
HTTP Status Codes
Code |
Desc |
200 OK |
Request accepted and there should be some content, assume the operation is complete. |
202 Accepted |
Request accepted but processing is not complete. The location header will point to a URL that will show the progress or final result. |
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 passing a BDE UUID for lookup that doesn’t exist. |
412 Precondition Failed |
When requesting a report that has not yet been generated. |
API Codes
E-BDE-100 |
400 |
entity |
File not processed. |
E-BDE-200 |
400 |
content-disposition |
Filename missing. |
E-BDE-201 |
400 |
content-disposition |
Length of filename is too long, must be 255 characters at most. |
E-BDE-300 |
409 |
file-structure |
At least one of the following headers is required in the file: Account_ID, Meter_ID, Location_ID. |
E-BDE-400 |
409 |
file-structure |
File only contains headers – must contain at least one row of data to perform import. |
Objects
Pagination
Results that are paginated are returned in a pagination wrapper object, with the actual objects under a results property.
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 |
offset |
int |
Record offset. |
limit |
int |
How many records to return. |
results |
Object array |
An array of the result objects–see API for type of object. |
BDENew
Object created at the time of a new BDE.
bdeType |
enum |
Type of BDE {input, read} |
bdeUUID |
uuid |
UUID of Typed BDE. |
statusUrl |
url |
URL to check on status of BDE execution. |
BDEResult
Object that returns information about a BDE.
bdeType |
enum |
Type of BDE {input, read} |
bdeUUID |
uuid |
UUID of Typed BDE. |
state |
enum |
Current state of a BDE {queue, run, exception, done} |
dryRun |
boolean |
True or false depending on whether the bde was a dry run or not. |
importOk |
int |
How many records were successfully validated or imported. |
importError |
int |
How many records were not successfully validated or imported. |
BDEReport
Upon completion the report available for a BDE.
originalUrl |
url |
URL to file that was uploaded. |
okCount |
int |
Number of records processed successfully. |
errorCount |
int |
Number of records processed erroneously. |
errorUrl |
url |
URL to file with records that were processed erroneously. |
errorSheetUrl |
url |
URL to CSV encoded file with records that were processed erroneously. |
dryRun |
boolean |
True or false depending on whether import is a dry run. |
BDEStatus
Calls that return status of a BDE.
startTime |
date |
Date that processing began. |
endTime |
date |
Date that processing stopped. |
queueTime |
date |
Date of upload. |
state |
enum |
Current state of a BDE {queue, run, exception, done} |
message |
string |
Human readable message describing state. |
progress |
Progress |
Current progress. |
reportUrl |
URL |
On completion of processing–where to find more detailed information. |
dryRun |
boolean |
true or false depending on whether the import is a dry run. |
Progress
Object describing the current progress of on-going work.
percentComplete |
float |
Current progress. |
ETA |
date |
Estimated date of completion. |
message |
string |
Description of current work. |
Last Update |
What Changed |
What You Need to Do |
October 18, 2017 |
Removed GET /v1/bde/import CURL commands for displaying all previous and pending files. Removed high-level logic diagram. |
No action required. |
February 11, 2016 |
New URL for accessing our API endpoints. Added API error codes. |
Update the URLs in your code per the documentation. |