Area Counter API

API Reference for Developers and System Integrators

Version 2.2 | Last updated: July 2026

This document provides a complete reference for integrating with the Metrici Area Counter system. The API allows you to retrieve real-time occupancy data for monitored areas, including locations, cameras, zones, and groups.

Overview
Quick Start
Base URL
Common Parameters
Response Format
Location Endpoints
Counter Endpoints
Events Endpoints
- List Events
Error Handling
Complete Integration Checklist
Notes

Overview

The Metrici Area Counter system tracks occupancy in real-time using video analytics. It monitors specific zones within camera views and provides aggregated counts of people or objects present in those zones.

The API is organized around a hierarchical structure:

Location (building, area, facility)
├── Camera 1
│   ├── Zone 1
│   └── Zone 2
├── Camera 2
│   └── Zone 3
└── Groups (logical collections of zones across cameras)
    ├── Group A (Zone 1 + Zone 3)
    └── Group B (Zone 2 + Zone 3)

Each entity (location, camera, zone, group) has three counter values:

capacity — maximum number of entities the area can hold
counter — current number of entities detected in the area
available — remaining capacity (capacity - counter)

Quick Start

Get the base URL from your Metrici system administrator.
Call the Locations endpoint to discover available locations and their IDs.
Query counters for the entity you need (location, camera, zone, or group).

Minimal Example (cURL)

# Step 1: Get all locations
curl "https://YOUR_HOST/api/ac/get_locations_list.php?output=json"

# Step 2: Get counters for a location (e.g., location ID = 5)
curl "https://YOUR_HOST/api/ac/get_counters_by_location.php?id=5&output=json"

Base URL

All endpoints are relative to:

https://YOUR_HOST/api/ac/

Replace YOUR_HOST with your Metrici server address.

Common Parameters

Parameter	Type	Required	Default	Description
`output`	string	No	`json`	Response format: `json`, `xml`, or `dump`

The output parameter is case-insensitive. The API normalizes all query parameters to lowercase internally.

Response Format

JSON (default)

Counter Response:

{
  "error": false,
  "response": {
    "capacity": 100,
    "counter": 42,
    "available": 58,
    "duration": "0.05"
  }
}

List Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 3,
      "duration": "0.03"
    },
    "body": [
      {
        "id": 1,
        "name": "Main Hall"
      },
      {
        "id": 2,
        "name": "Parking Lot"
      },
      {
        "id": 3,
        "name": "Conference Room"
      }
    ]
  }
}

XML

When output=xml, the response is formatted as XML with <item> elements in the body.

PHP Dump (debug)

When output=dump, the response is a PHP var_dump() output. Use only for debugging.

Location Endpoints

List Locations

Get a list of all locations that have Area Counter cameras configured.

Endpoint: GET /api/ac/get_locations_list.php

Parameters:

Parameter	Type	Required	Default	Description
`output`	string	No	`json`	Response format

Response Body Fields:

Field	Type	Description
`id`	int	Location ID (use in other endpoints)
`name`	string	Location name

Example:

curl "https://YOUR_HOST/api/ac/get_locations_list.php?output=json"

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 2,
      "duration": "0.04"
    },
    "body": [
      { "id": 5, "name": "Shopping Center" },
      { "id": 8, "name": "Office Building" }
    ]
  }
}

List Cameras by Location

Get all Area Counter cameras configured for a specific location.

Endpoint: GET /api/ac/get_cameras_list.php

Parameters:

Parameter	Type	Required	Default	Description
`id`	int	Yes	—	Location ID
`output`	string	No	`json`	Response format

Response Body Fields:

Field	Type	Description
`id`	int	Location ID
`name`	string	Location name
`cameras`	array	List of cameras belonging to this location
`cameras[].id`	int	Camera ID (use in counter endpoints)
`cameras[].name`	string	Camera name

Example:

curl "https://YOUR_HOST/api/ac/get_cameras_list.php?id=5&output=json"

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 1,
      "duration": "0.06"
    },
    "body": [
      {
        "id": 5,
        "name": "Shopping Center",
        "cameras": [
          { "id": 12, "name": "Entrance Camera" },
          { "id": 13, "name": "Food Court Camera" }
        ]
      }
    ]
  }
}

List Groups by Location

Get all zone groups configured for a specific location. Groups are logical collections of zones that can span multiple cameras.

Endpoint: GET /api/ac/get_groups_list.php

Parameters:

Parameter	Type	Required	Default	Description
`id`	int	Yes	—	Location ID
`output`	string	No	`json`	Response format

Response Body Fields:

Field	Type	Description
`id`	int	Group ID (use in counter endpoints)
`name`	string	Group name

Example:

curl "https://YOUR_HOST/api/ac/get_groups_list.php?id=5&output=json"

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 2,
      "duration": "0.03"
    },
    "body": [
      { "id": 1, "name": "Ground Floor" },
      { "id": 2, "name": "Upper Floors" }
    ]
  }
}

Get Counters by Location

Get aggregated occupancy counters for all zones within a location.

Endpoint: GET /api/ac/get_counters_by_location.php

Parameters:

Parameter	Type	Required	Default	Description
`id`	int	Yes	—	Location ID
`output`	string	No	`json`	Response format

Response Fields:

Field	Type	Description
`capacity`	int	Total capacity of all zones in this location
`counter`	int	Current number of entities detected across all zones
`available`	int	Remaining capacity (`capacity - counter`)
`duration`	string	Query execution time in seconds

Example:

curl "https://YOUR_HOST/api/ac/get_counters_by_location.php?id=5&output=json"

Example Response:

{
  "error": false,
  "response": {
    "capacity": 500,
    "counter": 234,
    "available": 266,
    "duration": "0.08"
  }
}

Counter Endpoints

Get Counters by Camera

Get occupancy counters for all zones monitored by a specific camera.

Endpoint: GET /api/ac/get_counters_by_camera.php

Parameters:

Parameter	Type	Required	Default	Description
`id`	int	Yes	—	Camera ID
`output`	string	No	`json`	Response format

Response Fields:

Field	Type	Description
`capacity`	int	Total capacity of all zones on this camera
`counter`	int	Current number of entities detected on this camera
`available`	int	Remaining capacity (`capacity - counter`)
`duration`	string	Query execution time in seconds

Example:

curl "https://YOUR_HOST/api/ac/get_counters_by_camera.php?id=12&output=json"

Example Response:

{
  "error": false,
  "response": {
    "capacity": 150,
    "counter": 67,
    "available": 83,
    "duration": "0.05"
  }
}

Get Counters by Zone

Get occupancy counters for a single zone.

Endpoint: GET /api/ac/get_counters_by_zone.php

Parameters:

Parameter	Type	Required	Default	Description
`id`	int	Yes	—	Zone ID
`output`	string	No	`json`	Response format

Response Fields:

Field	Type	Description
`capacity`	int	Maximum capacity of this zone
`counter`	int	Current number of entities in this zone
`available`	int	Remaining capacity (`capacity - counter`)
`duration`	string	Query execution time in seconds

Example:

curl "https://YOUR_HOST/api/ac/get_counters_by_zone.php?id=3&output=json"

Example Response:

{
  "error": false,
  "response": {
    "capacity": 50,
    "counter": 12,
    "available": 38,
    "duration": "0.03"
  }
}

Get Counters by Group

Get aggregated occupancy counters for all zones within a group. Groups can combine zones from different cameras, allowing you to monitor logical areas that span multiple camera views.

Endpoint: GET /api/ac/get_counters_by_group.php

Parameters:

Parameter	Type	Required	Default	Description
`id`	int	Yes	—	Group ID
`output`	string	No	`json`	Response format

Response Fields:

Field	Type	Description
`capacity`	int	Total capacity of all zones in this group
`counter`	int	Current number of entities detected across all zones in the group
`available`	int	Remaining capacity (`capacity - counter`)
`duration`	string	Query execution time in seconds

Example:

curl "https://YOUR_HOST/api/ac/get_counters_by_group.php?id=1&output=json"

Example Response:

{
  "error": false,
  "response": {
    "capacity": 300,
    "counter": 145,
    "available": 155,
    "duration": "0.07"
  }
}

Events Endpoints

List Events

Retrieve a list of occupancy change events within a date range. Each event represents a moment when the occupancy count changed in a monitored zone. Optionally filter by group.

Endpoint: GET /api/ac/list.php

Parameters:

Parameter	Type	Required	Default	Description
`auth`	string	Conditional	—	API authentication key (required when `use_api_key` is enabled)
`start`	string	No	7 days ago	Start date in `Y-m-d` format (e.g., `2026-07-01`)
`end`	string	No	Today	End date in `Y-m-d` format (e.g., `2026-07-30`)
`group_id`	int	No	—	Filter events by group ID. Omit to return events from all groups.
`output`	string	No	`json`	Response format

Authentication: When API key validation is enabled on the server, the auth parameter must be set to md5(start + end + group_id + api_key). Concatenate the parameter values (as sent in the request) with the server's API key, then compute the MD5 hash. Contact your system administrator for the API key.

Response Header Fields:

Field	Type	Description
`group_id`	int/null	The group ID used for filtering, or `null` if unfiltered
`count`	int	Total number of events returned
`duration`	string	Query execution time in seconds

Response Body Fields (per event):

Field	Type	Description
`id`	int	Event ID
`snapshot`	string	URL to the annotated snapshot image for this event
`zone_id`	int	Zone ID where the event occurred
`group`	string	Group name the zone belongs to (may be `null` if zone is ungrouped)
`counter`	int	Occupancy count at the time of the event
`object_type`	string	Type of object/entity counted (e.g., "person", "vehicle")
`changed_at`	string	Event timestamp in `Y-m-d H:i:s` format
`info`	string	Additional event information or notes
`location`	string	Location name where the event occurred
`camera`	string	Camera name that recorded the event
`has_companion`	int	`1` if a companion image is available, `0` otherwise
`companion_snapshot`	string	URL to the companion image (only present when `has_companion` is `1`)

Example — All events in date range:

curl "https://YOUR_HOST/api/ac/list.php?start=2026-07-01&end=2026-07-30&output=json"

Example — Events filtered by group:

curl "https://YOUR_HOST/api/ac/list.php?auth=ABC123&start=2026-07-15&end=2026-07-30&group_id=3&output=json"

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "group_id": null,
      "count": 2,
      "duration": "0.12"
    },
    "body": [
      {
        "id": 1042,
        "snapshot": "http://YOUR_HOST/ac/primary_image/1042",
        "zone_id": 7,
        "group": "Ground Floor",
        "counter": 45,
        "object_type": "person",
        "changed_at": "2026-07-20 14:32:10",
        "info": "",
        "location": "Shopping Center",
        "camera": "Entrance Camera",
        "has_companion": 0
      },
      {
        "id": 1098,
        "snapshot": "http://YOUR_HOST/ac/primary_image/1098",
        "zone_id": 3,
        "group": "Upper Floors",
        "counter": 23,
        "object_type": "person",
        "changed_at": "2026-07-25 09:15:44",
        "info": "Manual correction applied",
        "location": "Office Building",
        "camera": "Lobby Camera",
        "has_companion": 1,
        "companion_snapshot": "http://YOUR_HOST/ac/companion_image/1098"
      }
    ]
  }
}

Error Handling

All endpoints return a consistent error format. On failure, the API returns plain text:

Error Response

Status:-1

This response is returned for any error condition, including:

Cause	Solution
Missing required `id` parameter	Include the correct entity ID in your request
Invalid entity ID	Verify the ID using the list endpoints
Database connection failure	Contact the system administrator
Database query error	Contact the system administrator

Authentication Error (Events endpoint)

The list.php endpoint returns a JSON error when API key validation is enabled and the auth parameter is missing or invalid:

{
  "error": true
}

Cause	Solution
Missing `auth` parameter	Include a valid MD5 hash as described in the List Events section
Invalid `auth` hash	Verify the concatenation order: `start + end + group_id + api_key`
Wrong API key	Contact your system administrator for the correct key

Error Handling Example (cURL)

RESPONSE=$(curl -s "https://YOUR_HOST/api/ac/get_counters_by_location.php?id=5&output=json")

# Check for error
if echo "$RESPONSE" | grep -q "Status:-1"; then
  echo "API Error: request failed"
else
  echo "$RESPONSE" | python3 -m json.tool
fi

Error Handling Example (JavaScript)

async function getCounters(locationId) {
  const res = await fetch(`https://YOUR_HOST/api/ac/get_counters_by_location.php?id=${locationId}&output=json`);
  const text = await res.text();

  if (text === "Status:-1") {
    throw new Error("API request failed. Check the entity ID.");
  }

  return JSON.parse(text);
}

getCounters(5)
  .then(data => console.log(data.response.counter, "people present"))
  .catch(err => console.error(err.message));

Complete Integration Checklist

To integrate with Metrici Area Counter, follow these steps:

Get the base URL — Obtain your Metrici server address from the system administrator.
Discover Locations — Call get_locations_list.php to get all available locations and their IDs.
Discover Cameras — Call get_cameras_list.php?id={location_id} to get cameras for a location.
Discover Groups — Call get_groups_list.php?id={location_id} to get groups for a location.
Query Counters — Use the appropriate counter endpoint for your use case:
- get_counters_by_location.php — total occupancy for a location
- get_counters_by_camera.php — occupancy for a single camera
- get_counters_by_zone.php — occupancy for a single zone
- get_counters_by_group.php — occupancy for a group of zones
Retrieve Events — Call list.php to get historical occupancy change events, optionally filtered by date range and group.
Poll or Cache — The API returns real-time data. Poll at the frequency your application requires, or cache results if appropriate.

Notes

All endpoints use HTTP GET requests.
The API returns JSON by default. Use output=xml for XML or output=dump for debugging.
Query parameters are case-insensitive (the API normalizes them to lowercase internally).
The id parameter is required for all endpoints except get_locations_list.php and list.php.
The duration field in the response indicates server-side query execution time in seconds (rounded to 2 decimal places).
Counter values (capacity, counter, available) are aggregated sums across all relevant zones for the queried entity.
If a zone has no capacity configured, it will return null values. Handle this case in your integration.
Zone IDs are not returned by any list endpoint. You must obtain zone IDs from the Metrici admin panel or system administrator.
The list.php endpoint returns events ordered by database ID (chronological). Use start/end date parameters to limit result sets for large deployments.
Events returned by list.php may include a group value of null if the zone is not assigned to any group.

Example: Full Integration Flow

# 1. List all locations
curl "https://YOUR_HOST/api/ac/get_locations_list.php?output=json"
# → Returns locations with IDs

# 2. Pick a location (e.g., ID = 5) and get its cameras
curl "https://YOUR_HOST/api/ac/get_cameras_list.php?id=5&output=json"
# → Returns cameras under that location with their IDs

# 3. Get groups for the same location
curl "https://YOUR_HOST/api/ac/get_groups_list.php?id=5&output=json"
# → Returns groups with their IDs

# 4. Get real-time counters at different levels
curl "https://YOUR_HOST/api/ac/get_counters_by_location.php?id=5&output=json"
# → Total occupancy for the location

curl "https://YOUR_HOST/api/ac/get_counters_by_camera.php?id=12&output=json"
# → Occupancy for a specific camera

curl "https://YOUR_HOST/api/ac/get_counters_by_group.php?id=1&output=json"
# → Occupancy for a group of zones

# 5. Get historical occupancy events
curl "https://YOUR_HOST/api/ac/list.php?start=2026-07-01&end=2026-07-30&output=json"
# → All events in the date range

curl "https://YOUR_HOST/api/ac/list.php?start=2026-07-01&end=2026-07-30&group_id=1&output=json"
# → Events filtered by group

Area Counter API

Table of Contents

Overview

Quick Start

Minimal Example (cURL)

Base URL

Common Parameters

Response Format

JSON (default)

XML

PHP Dump (debug)

Location Endpoints

List Locations

List Cameras by Location

List Groups by Location

Get Counters by Location

Counter Endpoints

Get Counters by Camera

Get Counters by Zone

Get Counters by Group

Events Endpoints

List Events

Error Handling

Error Response

Authentication Error (Events endpoint)

Error Handling Example (cURL)

Error Handling Example (JavaScript)

Complete Integration Checklist

Notes

Example: Full Integration Flow