AquaCUE Web Services
Welcome to the AquaCUE Web Services API documentation pages. These pages are for software developers who wish to understand the capabilities of the AquaCUE Web Services API and to learn how to use it to extend and integrate AquaCUE with SCADA and other data management systems.
The AquaCUE Web Services API consists of different APIs: AquaCUE Data Exchange Import API and AquaCUE 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 AquaCUE features through code, you can extend the system and
create customized reports and other extensions to achieve specific requirements.
Use Cases
The AquaCUE Data Exchange Import API facilitates automatic system sync between SCADA and facility information systems and AquaCUE.
The AquaCUE Export Data Service API facilitates automatic flow and meter read exports from AquaCUE.
Best Practices
AquaCUE Web Services use HTTP basic access authentication to give your applications secure access to data available to your facility. We recommend that you set up a unique email account, AquaCUE user name and password for accessing AquaCUE Web Services. Having unique credentials for each AquaCUE Web Services-based report lets you create, for example, tailored usage reports and other analytics.
Example email and user name:
Email: yourfacilityname.eds@mail.com
User Name: EDS Meter Reads Report
Test Driving AquaCUE 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 AquaCUE using SSL protocol.
cURL Methods
| Command | What it Does |
| GET | Performs request operations by “getting” a URL. In AquaCUE, 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 AquaCUE, POST is used to export meter read data and initiate new file exchanges. |
| PUT | Uploads data to an HTTP server. In AquaCUE, PUT is used to proceed with an import operation after a dry run is accepted. |
API Endpoints
For all facailities except those in Canada, all API endpoints are accessed using web service URL:
https://api.beaconama.net
For facilities in Canada, API endpoints are accessed using the web 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 AquaCUE username and password.
- Enter AquaCUE 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
The 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 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
- Contact your Badger Meter support representative to request access to Web Services.
- 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 AquaCUE 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
