Welcome to the BEACON Web Services API documentation pages. These pages are for software developers who wish to understand the capabilities of the BEACON Web Services API and to learn how to use it to extend and integrate BEACON with billing and other data management systems.
(Last updated August 22, 2017)
The BEACON Web Services API consists of different APIs: BEACON Data Exchange Import API and BEACON Export Data Service API v1 and v2. The documentation explains how to authenticate and get access to the API endpoints, how to create requests to the various API methods and how to interpret the results of API responses.
By calling various BEACON features through code, you can extend the system and
create customized reports and other extensions to achieve specific requirements.
Use Cases
The BEACON Data Exchange Import API facilitates automatic system sync between billing and customer information systems and BEACON.
The BEACON Export Data Service API facilitates automatic flow and billing read exports from BEACON to billing systems.
Best Practices
BEACON Web Services use HTTP basic access authentication to give your applications secure access to data available to your utility. We recommend that you set up a unique email account, BEACON user name and password for accessing BEACON Web Services. Having unique credentials for each BEACON Web Services-based report lets you create, for example, tailored usage reports and other analytics.
Example email and user name:
Email: yourutilityname.eds@mail.com
User Name: EDS Billing Reads Report
Test Driving BEACON Web Services
The examples in our documentation are cURL statements. To try these statements without building a complete web application, run them in a command-line tool such as Terminal on a Mac or the command-line prompt in Windows. You can also run them in a browser using a plug-in such as Postman for Google® Chrome.
Mac OS X supports cURL natively. If you use Windows, you will need to download and install cURL along with a digital certificate that allows cURL to connect securely to BEACON using SSL protocol.
cURL Methods
| Command | What it Does |
| GET | Performs request operations by “getting” a URL. In BEACON, GET is used to request lists, the status of files and reports. |
| POST | Performs request operations for retrieving data too dense to include in a URL. In BEACON, POST is used to export billing read data and initiate new file exchanges. |
| PUT | Uploads data to an HTTP server. In BEACON, PUT is used to proceed with an import operation after a dry run is accepted. |
API Endpoints
For all utilities except those in Canada, all API endpoints are accessed using the BEACON API service URL:
https://api.beaconama.net
For utilities in Canada, API endpoints are accessed using the BEACON API service URL:
https://api.beaconama.ca
Programming Tips
When using the Postman plug-in for Google Chrome, set the Body radio button to
x-www-form-urlencoded
and use the following header with your requests:
Content-Type: application/x-www-form-urlencoded
Unless you are using cURL, you must pass query parameters, e.g. route=0113, as key-value lines in the body of the POST.
For example, pass
route=0366&date=2015-08-23&tolerance=72
in the body of the POST as
route=0366
date=2015-08-23
tolerance=72
When using cURL, by default it turns query parameters into key=value lines in the content of the POST.
Do not pass the –location-trusted flag when using cURL. This flag sends unneeded authorization headers that result in a 400 error. This is true when using the Microsoft WinHttpRequest COM object or working in other languages, such as Visual Basic, C#, C++, etc.
When using SOAP UI, after setting up the URL for your REST project and before proceeding with API testing:
- Select the Authentication & Security-related settings tab, enter your BEACON username and password.
- Enter BEACON AMA as the Domain and pick Authenticate Pre-emptively.
- Select the Header tab and click + to add a header.
- In the dialog box, type: Content-Type and press Enter.
- In the Value field, type: application/x-www-form-urlencoded.
- Under Attachment>Request>Media Type, check Post QueryString.
- Proceed with testing the API.
Rate Limits
BEACON Web Services APIs are rate-limited. Only a certain number of calls are allowed per utility in a given timeframe. The table below shows the default rate limits. Badger Meter reserves the right to adjust the rate limit at any time for its import and export APIs to provide a high quality of service for all of our customers.
| Rate Limit | Timeframe |
| 6 calls per | 60 seconds |
| 24 calls per | 60 minutes |
| 48 calls per | 24 hours |
Rate limits use sliding windows of time. For example, if the very first call to the BEACON Export Data Service API occurs at 11:00:00 on 2016-May-17, you could make x more calls until 10:59:59 on 2016-May-18. Similarly, if you start a data import at 11:15:23, you could make x more calls until 11:16:22.
Exceeding your rate limit produces an HTTP 429 Too Many Requests error code along with a message that includes the time remaining in seconds until the request will succeed.
It is also possible for the system to limit or throttle API calls when, for example, it detects a sharp increase in requests, which could indicate a possible denial of service attack.
Contact your Badger Meter support representative to determine a rate limit that suits your needs. Additional charges may apply.
Getting Started
- Admin users with native BEACON sign-in credentials (a username and password) have API access.
- Read the documentation to familiarize yourself with the API’s capabilities and determine suitability for your project.
- If you do not already have them, request an invite to use BEACON with admin-level access and create a user name and password. You will need these credentials to authenticate and provide your applications with secure access to all data available to your account.
- Build your application.
- Deploy your application.
Support
After you have been setup, Badger Meter will provide you with support contact information.
Documentation Pages
Get Support