Code examples

Full working examples for sending a meter reading request across seven languages and platforms.

Send a request

The default asynchronous flow. You'll receive a reference_id immediately and the result via webhook later.

curl

curl -X POST https://www.aquameter.site/api/meter-reading \
  -H "Authorization: Bearer aqm_live_YOUR_API_KEY" \
  -F "image=@/path/to/meter.jpg"

Using environment variables

Never hard-code your API key. Store it as an environment variable and read it at runtime.

.env

AQUAMETER_API_KEY=aqm_live_YOUR_API_KEY

JavaScript

const apiKey = process.env.AQUAMETER_API_KEY;

Python

import os
api_key = os.environ["AQUAMETER_API_KEY"]

PHP

$apiKey = getenv("AQUAMETER_API_KEY");

Java

String apiKey = System.getenv("AQUAMETER_API_KEY");

Flutter

// Use flutter_dotenv or similar:
final apiKey = dotenv.env['AQUAMETER_API_KEY']!;

Swift

let apiKey = ProcessInfo.processInfo.environment["AQUAMETER_API_KEY"]!

Handling the result via webhook

The API returns a reference_id immediately. The reading is delivered to your webhook URL once processing completes (typically within 1–3 seconds). Match the incoming reference_id to the request you stored. Always verify the X-AquaMeter-Signature header before trusting the payload — see Webhooks.

JavaScript

// Webhook handler (Express)
app.post("/webhook", express.json(), async (req, res) => {
  const { event, data } = req.body;

  if (event === "reading.completed") {
    const { reference_id, reading, confidence, unobstructed, escalated } = data;
    // Update the record you stored when you received reference_id from the API ack
    await db.meters.update(
      { reference_id },
      { reading, confidence, unobstructed, escalated, status: "completed" },
    );
  }

  if (event === "reading.failed") {
    const { reference_id, reason } = data;
    await db.meters.update({ reference_id }, { status: "failed", reason });
  }

  res.sendStatus(200);
});

Python

# Webhook handler (Flask)
@app.route("/webhook", methods=["POST"])
def webhook():
    payload = request.get_json()
    event = payload["event"]
    data = payload["data"]

    if event == "reading.completed":
        db.update_meter(
            reference_id=data["reference_id"],
            reading=data["reading"],
            confidence=data["confidence"],
            unobstructed=data["unobstructed"],
            escalated=data["escalated"],
            status="completed",
        )

    elif event == "reading.failed":
        db.update_meter(
            reference_id=data["reference_id"],
            status="failed",
            reason=data.get("reason"),
        )

    return "", 200

Error codes Webhooks