Data Exchange Import API

The Badger Meter Data Exchange (BDE) import service is based on the Common Services API and processes various AquaCUE data files through a standard programming interface. Data Exchange is used to keep the AquaCUE 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 AquaCUE.

---

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 facility via aquacue.ca you should adjust all of your API calls to address endpoints at api.beaconama.ca.

For example, change
https://api.beaconama.net/v1/eds/read/
to
https://api.beaconama.ca/v1/eds/read/

This change affects all API endpoint calls for facilities that login to beaconama.ca.

---

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 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 AquaCUE 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 30MB or less.

param	required	type	desc
data		CSV	The CSV file to be processed.

---

GET BDE status::Response::Queued

[sourcecode lang=”bash”]
{
“state”: “queue”,
“dryRun”: true,
“message”: “Provisioning Import operation queued for processing.”,
“queueTime”: “2015-01-14T23:50:59Z”
}
[/sourcecode]

---

GET BDE status::Response::Running

---

GET BDE status::Response::Exception

---

Response

Returns BDEStatus object.

GET /v1/bde/import/{bdeUUID}/report

Get report generated after the BDE has been processed.

Variables:

param	required	type	desc
bdeUUID		UUID	The bdeType UUID to get the report.

[sourcecode lang=”bash”]
# 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
#
[/sourcecode]

---

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

code	status	area	descriptionn
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.

property	type	desc
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.

property	type	desc
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.

property	type	desc
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.

property	type	desc
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.

property	type	desc
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.

property	type	desc
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.