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.

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

{    
    "state": "queue",
    "dryRun": true,
    "message": "Provisioning Import operation queued for processing.",
    "queueTime": "2015-01-14T23:50:59Z"
}

{    
    "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"
}

{
    "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"
}

{    
    "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

API Codes

Objects
Pagination
Results that are paginated are returned in a pagination wrapper object, with the actual objects under a results property.

BDENew
Object created at the time of a new BDE.

BDEResult

Object that returns information about a BDE.

BDEReport
Upon completion the report available for a BDE.

BDEStatus

Calls that return status of a BDE.

Progress

Object describing the current progress of on-going work.