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:

For utilities in Canada, API endpoints are accessed using the BEACON API service URL:

Programming Tips

When using the Postman plug-in for Google Chrome, set the Body radio button to


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


in the body of the POST as


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:

  1. Select the Authentication & Security-related settings tab, enter your BEACON username and password.
  2. Enter BEACON AMA as the Domain and pick Authenticate Pre-emptively.Soap UI authenticate
  3. Select the Header tab and click + to add a header.+ header 
  4. In the dialog box, type: Content-Type and press Enter.Screen Shot 2016-02-26 at 10.51.28 AM
  5. In the Value field, type: application/x-www-form-urlencoded.Screen Shot 2016-02-26 at 10.56.23 AM
  6. Under Attachment>Request>Media Type, check Post QueryString.Screen Shot 2016-03-16 at 1.19.07 PM.png
  7. 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

  1. Admin users with native BEACON sign-in credentials (a username and password) have API access.
  2. Read the documentation to familiarize yourself with the API’s capabilities and determine suitability for your project.
  3. 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.
  4. Build your application.
  5. Deploy your application.


After you have been setup, Badger Meter will provide you with support contact information.

Documentation Pages

Get Support

Knowledge Base

User Guide
Follow via Email

Enter your email address to get new content notifications by email.