Version 1.7 | Last updated: July 2026

This document provides a complete reference for integrating with the Metrici PPD (Parking Place Detector) system. The API allows you to query individual parking spaces, monitor occupancy status, manage groups, and retrieve real-time availability counters across locations, cameras, and groups.

Table of Contents

• Quick Start
• Authentication
• Common Parameters
• Response Format
• Entity Endpoints
  • List Locations
  • List Cameras by Location
  • List Groups by Location
  • List Places by Location
  • List Places by Camera
  • List Places by Group
  • Get Status of Place
• Counter Endpoints
  • Counters by Location
  • Counters by Camera
  • Counters by Group
• Error Handling
• Integration Flow
• Code Examples
• Appendix: Status Codes

Quick Start

Base URL:

http://<server>/api/ppd/

Minimal example — get free spots at a location:

curl "http://<server>/api/ppd/get_counters_by_location.php?id=1&output=json"

Response:

{
  "error": false,
  "response": {
    "total": 50,
    "free": 12,
    "busy": 38,
    "duration": "0.03"
  }
}

Authentication

The PPD API does not require authentication. All endpoints are publicly accessible via HTTP GET.

Common Parameters

Response Format

JSON (default)

All endpoints return a consistent JSON structure:

{
  "error": false,
  "response": {
    "header": {
      "count": 5,
      "duration": "0.02"
    },
    "body": [ ... ]
  }
}

Counter Endpoints

Counter endpoints use a flattened response (no body array):

{
  "error": false,
  "response": {
    "total": 50,
    "free": 12,
    "busy": 38,
    "duration": "0.03"
  }
}

XML

Set output=xml to receive XML-formatted responses:

<?xml version="1.0"?>
<body>
  <item>
    <id>1</id>
    <name>Main Parking</name>
  </item>
</body>

Debug

Set output=dump to receive a PHP var_dump() output for debugging:

curl "http://<server>/api/ppd/get_locations_list.php?output=dump"

Entity Endpoints

List Locations

Get all parking locations that have at least one PPD camera (camera_type_id = 4).

Endpoint:

GET /api/ppd/get_locations_list.php

Parameters: None

Example:

curl "http://<server>/api/ppd/get_locations_list.php?output=json"

Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 2,
      "duration": "0.01"
    },
    "body": {
      "1": {
        "id": 1,
        "name": "Main Parking"
      },
      "2": {
        "id": 3,
        "name": "Underground Garage"
      }
    }
  }
}

Response fields:

List Cameras by Location

Get the location and all its PPD cameras. The response nests cameras inside the location object.

Endpoint:

GET /api/ppd/get_cameras_list.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_cameras_list.php?id=1&output=json"

Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 1,
      "duration": "0.02"
    },
    "body": {
      "1": {
        "id": 1,
        "name": "Main Parking",
        "cameras": {
          "0": {
            "id": 10,
            "name": "Camera A - Level 1"
          },
          "1": {
            "id": 11,
            "name": "Camera B - Level 2"
          }
        }
      }
    }
  }
}

Response fields:

List Groups by Location

Get all place groups defined for a location. Groups are logical collections of parking spaces (e.g., "VIP Section", "Electric Vehicle Charging", "Disabled Parking").

Endpoint:

GET /api/ppd/get_groups_list.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_groups_list.php?id=1&output=json"

Response:

{
  "error": false,
  "response": {
    "header": {
      "count": 3,
      "duration": "0.01"
    },
    "body": {
      "1": {
        "id": 5,
        "name": "VIP Section"
      },
      "2": {
        "id": 8,
        "name": "EV Charging"
      },
      "3": {
        "id": 12,
        "name": "Disabled Parking"
      }
    }
  }
}

Response fields:

List Places by Location

Get all registered parking spaces for a location, including their current status and coordinates.

Endpoint:

GET /api/ppd/get_places_by_location.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_places_by_location.php?id=1&output=json"

Response:

{
  "error": false,
  "response": {
    "header": {
      "camera_id": 1,
      "count": 50,
      "duration": "0.04"
    },
    "body": {
      "1": {
        "id": 101,
        "status": 0,
        "changed_at": "2026-07-30 10:15:22",
        "camera_id": 10,
        "x": 120,
        "y": 85
      },
      "2": {
        "id": 102,
        "status": 1,
        "changed_at": "2026-07-30 10:12:05",
        "camera_id": 10,
        "x": 145,
        "y": 85
      }
    }
  }
}

Response fields:

List Places by Camera

Get all registered parking spaces monitored by a specific camera.

Endpoint:

GET /api/ppd/get_places_by_camera.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_places_by_camera.php?id=10&output=json"

Response:

{
  "error": false,
  "response": {
    "header": {
      "camera_id": 10,
      "count": 25,
      "duration": "0.02"
    },
    "body": {
      "1": {
        "id": 101,
        "status": 0,
        "changed_at": "2026-07-30 10:15:22",
        "x": 120,
        "y": 85
      },
      "2": {
        "id": 102,
        "status": 1,
        "changed_at": "2026-07-30 10:12:05",
        "x": 145,
        "y": 85
      }
    }
  }
}

Response fields:

List Places by Group

Get all parking spaces that belong to a specific group.

Endpoint:

GET /api/ppd/get_places_by_group.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_places_by_group.php?id=5&output=json"

Response:

{
  "error": false,
  "response": {
    "header": {
      "group_id": 5,
      "count": 10,
      "duration": "0.02"
    },
    "body": {
      "1": {
        "id": 201,
        "status": 0,
        "changed_at": "2026-07-30 09:45:10",
        "group_id": 5,
        "camera_id": 10,
        "x": 200,
        "y": 150
      },
      "2": {
        "id": 202,
        "status": 1,
        "changed_at": "2026-07-30 10:01:33",
        "group_id": 5,
        "camera_id": 10,
        "x": 225,
        "y": 150
      }
    }
  }
}

Response fields:

Get Status of Place

Get the current status of a single parking space. This is the most granular endpoint, useful for checking individual spots.

Endpoint:

GET /api/ppd/get_status_of_place.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_status_of_place.php?id=101&camera_id=10&output=json"

Response:

{
  "error": false,
  "response": {
    "space_id": 101,
    "camera_id": 10,
    "status": 0,
    "x": 120,
    "y": 85,
    "header": {
      "duration": "0.01"
    }
  }
}

Response fields:

Counter Endpoints

Counter endpoints return aggregate occupancy data: total spaces, free spaces, and occupied spaces.

Counters by Location

Get occupancy counters for an entire location (all cameras combined).

Endpoint:

GET /api/ppd/get_counters_by_location.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_counters_by_location.php?id=1&output=json"

Response:

{
  "error": false,
  "response": {
    "total": 50,
    "free": 12,
    "busy": 38,
    "duration": "0.03"
  }
}

Counters by Camera

Get occupancy counters for a specific camera.

Endpoint:

GET /api/ppd/get_counters_by_camera.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_counters_by_camera.php?id=10&output=json"

Response:

{
  "error": false,
  "response": {
    "total": 25,
    "free": 8,
    "busy": 17,
    "duration": "0.02"
  }
}

Counters by Group

Get occupancy counters for a specific group of spaces.

Endpoint:

GET /api/ppd/get_counters_by_group.php

Parameters:

Example:

curl "http://<server>/api/ppd/get_counters_by_group.php?id=5&output=json"

Response:

{
  "error": false,
  "response": {
    "total": 10,
    "free": 3,
    "busy": 7,
    "duration": "0.02"
  }
}

Error Handling

HTTP Status Codes

Error Response

On logical errors, the response follows the standard format:

{
  "error": true,
  "response": {
    "message": "Description of the error"
  }
}

Server/Database Errors

On database connection or query failures, the server returns plain text:

Status:-1

This indicates a server-side issue (database unreachable, query failure). Implement retry logic with exponential backoff for these cases.

Missing Required Parameters

If a required parameter (id, camera_id) is missing, the server returns:

Status:-1

Integration Flow

Typical workflow to display parking availability:

1. GET /api/ppd/get_locations_list.php
   └──> Get all parking locations

2. GET /api/ppd/get_counters_by_location.php?id=<location_id>
   └──> Get free/busy counters for location

3. GET /api/ppd/get_cameras_list.php?id=<location_id>
   └──> Get cameras at this location

4. GET /api/ppd/get_places_by_camera.php?id=<camera_id>
   └──> Get individual spaces with status + coordinates

5. GET /api/ppd/get_status_of_place.php?id=<space_id>&camera_id=<camera_id>
   └──> Check single space status (polling)

For group-based queries:

1. GET /api/ppd/get_groups_list.php?id=<location_id>
   └──> Get all groups at this location

2. GET /api/ppd/get_counters_by_group.php?id=<group_id>
   └──> Get counters for specific group

3. GET /api/ppd/get_places_by_group.php?id=<group_id>
   └──> Get spaces in this group

Code Examples

PHP — Check Availability

<?php
$locationId = 1;
$url = "http://<server>/api/ppd/get_counters_by_location.php?id={$locationId}&output=json";

$response = file_get_contents($url);
$data = json_decode($response, true);

if ($data['error'] === false) {
    $total = $data['response']['total'];
    $free  = $data['response']['free'];
    $busy  = $data['response']['busy'];
    $pct   = round(($free / $total) * 100, 1);

    echo "Parking: {$free}/{$total} free ({$pct}%)\n";
} else {
    echo "Error fetching parking data\n";
}
?>

Python — List All Spaces

import requests

server = "http://<server>"
location_id = 1

# Get counters
counters = requests.get(f"{server}/api/ppd/get_counters_by_location.php", params={
    "id": location_id,
    "output": "json"
}).json()

print(f"Free: {counters['response']['free']}, Busy: {counters['response']['busy']}")

# Get all places
places = requests.get(f"{server}/api/ppd/get_places_by_location.php", params={
    "id": location_id,
    "output": "json"
}).json()

for key, space in places["response"]["body"].items():
    status = "FREE" if space["status"] == 0 else "BUSY"
    print(f"Space {space['id']}: {status} at ({space['x']}, {space['y']})")

JavaScript — Poll Single Space

async function checkSpace(spaceId, cameraId) {
  const url = `http://<server>/api/ppd/get_status_of_place.php`
    + `?id=${spaceId}&camera_id=${cameraId}&output=json`;

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

  if (!data.error) {
    const isFree = data.response.status === 0;
    console.log(`Space ${spaceId}: ${isFree ? 'FREE' : 'OCCUPIED'}`);
    return isFree;
  }
  throw new Error('Failed to fetch space status');
}

// Poll every 10 seconds
setInterval(() => checkSpace(101, 10), 10000);

cURL — Quick Check

# Location availability
curl -s "http://<server>/api/ppd/get_counters_by_location.php?id=1&output=json" | jq .response

# Single space status
curl -s "http://<server>/api/ppd/get_status_of_place.php?id=101&camera_id=10&output=json" | jq .response.status

# All spaces at camera
curl -s "http://<server>/api/ppd/get_places_by_camera.php?id=10&output=json" | jq '.response.body | length'

Appendix: Status Codes

Appendix: Endpoint Summary

Appendix: Data Hierarchy

Location (parking facility)
├── Camera (PPD camera — camera_type_id = 4)
│   └── Place / Space (parking spot)
│       ├── id (space_id)
│       ├── status (0 = free, 1 = busy)
│       ├── changed_at
│       ├── x (coordinate on image)
│       └── y (coordinate on image)
├── Group (logical collection of spaces)
│   └── Place / Space
└── ...