Data Exchange 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 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 utility 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 aquacue.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.

<span style="color: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.

<span style="color: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 (error) 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

PUT /v1/bde/import/{bdeUUID}

Accept the dry run of a BDE.

Variables:

param required type desc
bdeUUID (error) 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 desc
bdeUUID (error) 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 desc
bdeUUID (error) 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

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



User Guide