# ExCam Cameras Database Protocol

(Extensible Cameras Format – yet another cameras database standard)

### Reasoning

With that amount of existing POI-database formats, developing another one may not seem to be the best idea. However, most formats are proprietary and non-extensible. ExCam format is free for everyone, and supports conversion from other format. ExCam may be further developed in future; however, all new additions should be fully backward-compatible with previous versions.

ExCam standard is developed specifically for storing databases of road cameras. The main features of this standard are the following:

• Easily extensible in future, without losing backwards compatibility
• Designed for modern devices, doesn’t have compromises for low-power/low-memory/low-storage units
• Has offline (distribution as a file), and online (auto-update) variants
• Open to everyone, without any restrictions

## Format description

All JSON objects may be undocumented fields, which be ignored. Any code working with ExCam format should never fail because of unknown JSON fields

### Database file

Database files are used to store the cameras themselves. On the top level, database file is a JSON-lines file, encoded with UTF-8, and packed to XZ container (LZMA). The first line contains file metadata. The second and subsequent lines describe cameras, one per line.

Metadata is stored on the first line of the file after unpacking (XZ) and decoding (UTF-8).

Metadata line contains a JSON object with only one key: _meta. The value of the _meta key is another JSON object, containing the metadata itself. The following fields may be used in metadata:

• name (required) – the name of the database
• date (required) - the date of the dataset, must follow YYYY-MM-DD format
• revision (optional) - revision of the dataset within the same day, should be assumed as 0 if not specified in JSON

{"_meta": {"date": "2020-01-01", "name": "My cameras database"}}

{"_meta": {"date": "2020-01-01", "name": "My cameras database", "revision": 3}}


Cameras information*

Cameras are stored on the second and subsequent lines of the file after unpacking (XZ) and decoding (UTF-8), up to the end of file.

Each line with camera contains a JSON dictionary with the following keys:

• lat (required) - latitude of the camera
• lon (required) - longitude of the camera
• flg (required) - an integer containing information (bitmask) about boolean flags associated with that camera, will be described below
• dir (optional) - a list of controlled padding directions (integers), in degrees, starting from true North, clockwise; null if unknown; should be treated as null if omitted in JSON
(for example, [90, 180] means that camera watches for cars passing eastbound and southbound)
• spd (optional) - speed limit in km/h, if enforced; null if unknown or not enforced; should be treated as null if omitted in JSON
• str (optional) - name of the location, where the camera is located; null if unknown; should be treated as null if omitted in JSON

flg property contains a bitmask of various flags. The following flags and associated bitmask values are supported now. Bits are counted from lower to higher.

• (Bit 0) - Speed is enforced
• (Bit 1) - Red light is enforced
• (Bit 2) - Start of average speed enforcement section
• (Bit 3) - End of average speed enforcement section (may be combined with the previos flag to indicate a middle camera of section enforcement)
• (Bit 4) - Lane is enforced
• (Bit 5) - Bus lane is enforced
• (Bit 6) - This is a dummy camera
• (Bit 7) - Distance is enforced
• (Bit 8) - Overtaking is enforced
• (Bit 9) - Pedestrian crossing is enforced
• (Bit 10) - Height is enforced
• (Bit 11) - Weidth is enforced
• (Bit 12) - Entrance is enforced
…More flags may be added in future

Examples of correct cameras lines

{"lat": 47.23907, "lon": -122.35685, "flg":3, "dir":[179, 90], "spd":32, "str": "54th & 20th"}

{"lat":37.5362, "lon":-121.9985, "flg":2}


Python example of reading the database file

import json
import lzma

with lzma.open(excam_file_path, "rt", encoding="utf-8") as f:
print(
)
for camera in lines:
print(
f"Camera on {camera['lat']},{camera['lon']}, "
f"flags {camera['flg']:012b}, "
f"controlled directions {camera.get('dir')}, "
f"speed {camera.get('spd')}, "
f"street {camera.get('str')}"
)


The ExCam format has an extension allowing to update database automatically. To achieve this without downloading excessive data, a link to database format is used.

Online format works the following way

• A link to a web page is used as an identifier of the dataset
• The page above should return a special link structure describing
• the date of the current dataset (same as in metadata)
• the revision of the current dataset (same as in metadata)
• the download path to the database file of the current dataset (in the format described above)
• If based on that information, an update for the dataset is available/needed, it can be downloaded automatically

The format of the link structure

Link structure is a JSON object with only one key: _link. The value of the _link key is another JSON object, containing the link data itself. The following fields may be used in the link data:

• date (required) - the date of the dataset, must follow YYYY-MM-DD format
• revision (optional) - revision of the dataset within the same day, should be assumed as 0 if not specified in JSON
• dataUrl (required) - the URL path to the database file

{"_link":{"dataUrl": "https://example.com/database_file.excam", "date": "2020-01-01"}}

{"_link":{"dataUrl": "https://example.com/database_file.excam", "date": "2020-01-01", "revision": 3}}