Version 1.3 | Last updated: July 2025

This document provides a complete reference for integrating with the Metrici LC (Line Counter) system. The API allows you to query object detection events, retrieve real-time occupancy counters, and manage the hierarchical structure of locations, zones, and gates.

Table of Contents

• Overview
• Quick Start
• Base URL
• Authentication
• Common Parameters
• Response Format
• Location Endpoints
  • List Locations
  • List Cameras by Location
  • List Zones by Location
  • List Gates by Zone
  • Get Counters by Location
• Counter Endpoints
  • Get Counters by Camera
  • Get Counters by Zone
  • Get Counters by Gate
• Event Endpoints
  • List Events
• Error Handling
• Complete Integration Checklist
• Notes

Overview

The Metrici LC system tracks objects (boats, ships, cars, people, etc) in locations using video analytics. It monitors specific zones within camera views and records events as objects pass through defined gates (entry/exit points).

The API is organized around a hierarchical structure:

Location (marina, port, facility)
├── Camera 1
│   └── Zone 1
│       ├── Gate A (entry)
│       └── Gate B (exit)
├── Camera 2
│   └── Zone 2
│       └── Gate C (entry)
└── ...

Each entity (location, camera, zone, gate) has a counter value:

• counter — total number of detection events recorded for this entity

Quick Start

1. Get the base URL from your Metrici system administrator.
2. Get your API key (required only for the list.php endpoint).
3. Call the Locations endpoint to discover available locations and their IDs.
4. Query counters or events for the entity you need.

Minimal Example (cURL)

# Step 1: Get all locations (no auth required)
curl "https://YOUR_HOST/api/lc/get_locations_list.php?output=json"

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

# Step 3: List events for the last 7 days (auth required)
AUTH=$(echo -n "${API_KEY}" | md5sum | awk '{print $1}')
curl "https://YOUR_HOST/api/lc/list.php?auth=${AUTH}&output=json"

Base URL

All endpoints are relative to:

https://YOUR_HOST/api/lc/

Replace YOUR_HOST with your Metrici server address.

Authentication

Most LC endpoints do not require authentication. Only the list.php endpoint (which returns detailed event data) requires an auth parameter.

How to Generate the Auth Token

The auth token is an MD5 hash computed as follows:

auth = md5(to_concat + api_key)

Where:

• api_key — your secret API key (from the admin panel)
• to_concat — a concatenation of specific request parameters, in a specific order

Auth Token Generation for list.php

The parameters are concatenated in this order:

to_concat = start + end + zone_id + output

Only include parameters that are actually provided in the request. If a parameter is omitted, it is not included in the concatenation.

PHP Example

$api_key = 'YOUR_API_KEY';

// Example: no optional parameters
$auth = md5($api_key);

// Example: with start and end dates
$start = '2025-07-01';
$end = '2025-07-15';
$auth = md5($start . $end . $api_key);

// Example: with zone filter
$zone_id = '3';
$auth = md5($start . $end . $zone_id . 'json' . $api_key);

Python Example

import hashlib

api_key = 'YOUR_API_KEY'
start = '2025-07-01'
end = '2025-07-15'
zone_id = '3'

# With all parameters
to_concat = start + end + zone_id + 'json'
auth = hashlib.md5((to_concat + api_key).encode()).hexdigest()

# Without optional parameters
auth = hashlib.md5(api_key.encode()).hexdigest()

JavaScript Example

// Node.js
const crypto = require('crypto');
const api_key = 'YOUR_API_KEY';
const start = '2025-07-01';
const end = '2025-07-15';

const to_concat = start + end;
const auth = crypto.createHash('md5').update(to_concat + api_key).digest('hex');

Common Parameters

Response Format

JSON (default)

Counter Response:

{
  "error": false,
  "response": {
    "counter": 156,
    "duration": "0.05"
  }
}

List Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 3,
      "duration": "0.03"
    },
    "body": [
      {
        "id": 1,
        "name": "North Dock"
      },
      {
        "id": 2,
        "name": "South Dock"
      },
      {
        "id": 3,
        "name": "Main Basin"
      }
    ]
  }
}

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 LC cameras configured.

Endpoint: GET /api/lc/get_locations_list.php

Parameters:

Response Body Fields:

Example:

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

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 2,
      "duration": "0.04"
    },
    "body": [
      { "id": 5, "name": "Marina Central" },
      { "id": 8, "name": "Port North" }
    ]
  }
}

List Cameras by Location

Get all LC cameras configured for a specific location.

Endpoint: GET /api/lc/get_cameras_list.php

Parameters:

Response Body Fields:

Example:

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

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 1,
      "duration": "0.06"
    },
    "body": [
      {
        "id": 5,
        "name": "Marina Central",
        "cameras": [
          { "id": 12, "name": "Entrance Camera" },
          { "id": 13, "name": "Basin Camera" }
        ]
      }
    ]
  }
}

List Zones by Location

Get all zones configured for a specific location. Zones are logical areas within a location where object detection is active.

Endpoint: GET /api/lc/get_zones_list.php

Parameters:

Response Body Fields:

Example:

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

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 3,
      "duration": "0.03"
    },
    "body": [
      { "id": 1, "name": "North Dock" },
      { "id": 2, "name": "South Dock" },
      { "id": 3, "name": "Main Basin" }
    ]
  }
}

List Gates by Zone

Get all gates configured for a specific zone. Gates are entry/exit points where object passage is detected and recorded.

Endpoint: GET /api/lc/get_gates_list.php

Parameters:

Response Body Fields:

Example:

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

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 2,
      "duration": "0.03"
    },
    "body": [
      { "id": 10, "name": "Entrance Gate" },
      { "id": 11, "name": "Exit Gate" }
    ]
  }
}

Get Counters by Location

Get the total number of object detection events for all zones and gates within a location.

Endpoint: GET /api/lc/get_counters_by_location.php

Parameters:

Response Fields:

Example:

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

Example Response:

{
  "error": false,
  "response": {
    "counter": 1247,
    "duration": "0.08"
  }
}

Counter Endpoints

Get Counters by Camera

Get the total number of object detection events for all zones monitored by a specific camera.

Endpoint: GET /api/lc/get_counters_by_camera.php

Parameters:

Response Fields:

Example:

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

Example Response:

{
  "error": false,
  "response": {
    "counter": 432,
    "duration": "0.05"
  }
}

Get Counters by Zone

Get the total number of object detection events for all gates within a zone.

Endpoint: GET /api/lc/get_counters_by_zone.php

Parameters:

Response Fields:

Example:

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

Example Response:

{
  "error": false,
  "response": {
    "counter": 215,
    "duration": "0.03"
  }
}

Get Counters by Gate

Get the total number of object detection events for a single gate.

Endpoint: GET /api/lc/get_counters_by_gate.php

Parameters:

Response Fields:

Example:

curl "https://YOUR_HOST/api/lc/get_counters_by_gate.php?id=10&output=json"

Example Response:

{
  "error": false,
  "response": {
    "counter": 108,
    "duration": "0.03"
  }
}

Event Endpoints

List Events

Get a detailed list of all object detection events within a date range, optionally filtered by zone. This is the most comprehensive endpoint, providing full event data including object type, dimensions, direction, and image URLs.

Endpoint: GET /api/lc/list.php

Parameters:

Auth Token Generation:

auth = md5(start + end + zone_id + output + api_key)

Response Header Fields:

Response Body Fields:

Example:

# List all events from the last 7 days
AUTH=$(echo -n "${API_KEY}" | md5sum | awk '{print $1}')
curl "https://YOUR_HOST/api/lc/list.php?auth=${AUTH}&output=json"

# List events for a specific date range and zone
AUTH=$(echo -n "2025-07-012025-07-153json${API_KEY}" | md5sum | awk '{print $1}')
curl "https://YOUR_HOST/api/lc/list.php?start=2025-07-01&end=2025-07-15&zone_id=3&auth=${AUTH}&output=json"

Example Response:

{
  "error": false,
  "response": {
    "header": {
      "zone_id": "3",
      "count": 2,
      "duration": "0.12"
    },
    "body": [
      {
        "id": 1001,
        "ship_snapshot": "http://YOUR_HOST/lc/primary_image/1001",
        "zone": "Main Basin",
        "direction": "In",
        "gate": "Entrance Gate",
        "ship_type": "Sailboat",
        "registred_at": "2025-07-10 14:30:00",
        "location": "Marina Central",
        "camera": "Basin Camera",
        "has_companion": 1,
        "companion_snapshot": "http://YOUR_HOST/lc/companion_image/1001"
      },
      {
        "id": 1002,
        "ship_snapshot": "http://YOUR_HOST/lc/primary_image/1002",
        "zone": "Main Basin",
        "direction": "Out",
        "gate": "Exit Gate",
        "ship_type": "Motorboat",
        "registred_at": "2025-07-10 16:45:00",
        "location": "Marina Central",
        "camera": "Basin Camera",
        "has_companion": 0
      }
    ]
  }
}

Error Handling

All endpoints return a consistent error format. On failure, most endpoints return plain text:

Counter and List Endpoints

Status:-1

This response is returned for any error condition, including:

list.php Authentication Error

{
  "error": true
}

Error Handling Example (cURL)

RESPONSE=$(curl -s "https://YOUR_HOST/api/lc/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 getEventList(startDate, endDate, zoneId) {
  const api_key = 'YOUR_API_KEY';

  // Build auth token
  let to_concat = '';
  if (startDate) to_concat += startDate;
  if (endDate) to_concat += endDate;
  if (zoneId) to_concat += zoneId;
  to_concat += 'json';
  const auth = crypto.createHash('md5').update(to_concat + api_key).digest('hex');

  // Build URL
  let url = `https://YOUR_HOST/api/lc/list.php?auth=${auth}&output=json`;
  if (startDate) url += `&start=${startDate}`;
  if (endDate) url += `&end=${endDate}`;
  if (zoneId) url += `&zone_id=${zoneId}`;

  const res = await fetch(url);
  const data = await res.json();

  if (data.error) {
    throw new Error("API request failed. Check auth token and parameters.");
  }

  return data;
}

getEventList('2025-07-01', '2025-07-15', 3)
  .then(data => console.log(`${data.response.header.count} events found`))
  .catch(err => console.error(err.message));

Complete Integration Checklist

To integrate with Metrici LC, follow these steps:

1. Get the base URL — Obtain your Metrici server address from the system administrator.
2. Get your API key — Required only for the list.php endpoint. Obtain from the admin panel.
3. Discover Locations — Call get_locations_list.php to get all available locations and their IDs.
4. Discover Cameras — Call get_cameras_list.php?id={location_id} to get cameras for a location.
5. Discover Zones — Call get_zones_list.php?id={location_id} to get zones for a location.
6. Discover Gates — Call get_gates_list.php?id={zone_id} to get gates for a zone.
7. Query Counters — Use the appropriate counter endpoint for your use case:
   • get_counters_by_location.php — total events for a location
   • get_counters_by_camera.php — events for a single camera
   • get_counters_by_zone.php — events for a single zone
   • get_counters_by_gate.php — events for a single gate
8. Query Events — Use list.php with date range and optional zone filter to get detailed event data.
9. Poll or Cache — Counter endpoints return cumulative totals. Event endpoints return filtered results. Poll at the frequency your application requires.

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 represent cumulative event counts (not real-time occupancy). They count all events ever recorded for the queried entity.
• The list.php endpoint returns events filtered by date range. Default range is the last 7 days.
• Image URLs (ship_snapshot, companion_snapshot) are generated dynamically and include the event ID.
• The has_companion field indicates whether a companion image is available for the event. The companion_snapshot field is only present when has_companion is 1.

Example: Full Integration Flow

# 1. List all locations
curl "https://YOUR_HOST/api/lc/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/lc/get_cameras_list.php?id=5&output=json"
# → Returns cameras under that location with their IDs

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

# 4. Get gates for a specific zone (e.g., zone ID = 1)
curl "https://YOUR_HOST/api/lc/get_gates_list.php?id=1&output=json"
# → Returns gates with their IDs

# 5. Get event counters at different levels
curl "https://YOUR_HOST/api/lc/get_counters_by_location.php?id=5&output=json"
# → Total events for the location

curl "https://YOUR_HOST/api/lc/get_counters_by_zone.php?id=1&output=json"
# → Events for a specific zone

curl "https://YOUR_HOST/api/lc/get_counters_by_gate.php?id=10&output=json"
# → Events for a specific gate

# 6. Get detailed event list (auth required)
AUTH=$(echo -n "2025-07-012025-07-15json${API_KEY}" | md5sum | awk '{print $1}')
curl "https://YOUR_HOST/api/lc/list.php?start=2025-07-01&end=2025-07-15&auth=${AUTH}&output=json"
# → Full event details with object type, direction, images