Web Services

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.

Export-API

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:

  1. Select the Authentication & Security-related settings tab, enter your AquaCUE username and password.
  2. Enter AquaCUE 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

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

  1. Contact your Badger Meter support representative to request access to Web Services.
  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 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.
  4. Build your application.
  5. Deploy your application.

Support

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

Documentation Pages

KNOWLEDGE BASE



User Guide