Curb Data Specification: Events API

October 27, 2025 · View on GitHub

The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, directly from operators, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API.

See other CDS APIs on the homepage.

Endpoints

There are two different endpoints that are part of the Events API:

A Curb Event is an activity that occurs near, at, or within a pre-defined curb area. Defining events is required as part of the Events API.
A Status is the current status of a curb monitoring source. Event status is optional.

See examples for these endpoints.

REST Endpoints
- Authorization
Data Objects
- Curb Event
- Status
Examples
Schema

REST Endpoints

All endpoints return a JSON object containing the fields as specified in the REST Endpoint details.

Name	Type	Description
`event_time`	String	An ISO 8601 extended datetime representing an UTC hour between 00 and 23 in format `YYYY-MM-DDTHH`. Specifies the hour for which data should be returned. If omitted the API should return all events in the last 60 minutes. For example, requesting `event_time=2019-10-01T07` returns all events where `2019-10-01T07:00:00 <= event.event_time < 2019-10-01T08:00:00` UTC.
`curb_area_id`	UUID	The ID of a Curb Area. If specified, only return events occurring within this area.
`curb_zone_id`	UUID	The ID of a Curb Zone. If specified, only return events occurring within this zone.
`curb_space_id`	UUID	The ID of a Curb Space. If specified, only return events occurring within this space.
`curb_object_id`	UUID	The ID of a Curb Object. If specified, only return events occurring at this object.

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`missing_param`	A required parameter is missing	Array of missing parameters

Name	Type	Required/Optional	Description
`event_id`	UUID	Required	The globally unique identifier of the event that occurred.
`event_type`	Event Type	Required	The event_type that happened for this event.
`event_purpose`	Event Purpose	Conditionally Required	General curb usage purpose that the vehicle performed during the event. Required for sources capable of determining activity type for relevant event_types.
`event_location`	GeoJSON Point	Optional	The geographic point location where the event occurred. All efforts should be made to provide this field, even if slightly imprecise. But there may be times when a location is impossible or irrelevant.
`event_time`	Timestamp	Required	Time at which the event occurred.
`event_publication_time`	Timestamp	Required	Time at which the event became available for consumption by this API.
`event_session_id`	UUID	Optional	May be provided to tie known connected `park_start` and `park_end` event types together by a unique session ID. If not confident of being able to determine a `park_end` event at some time after `park_start` is recorded (i.e., you cannot detect when a vehicle departs), then do not use session_id. This field may be most useful to payment companies who provide their source data as sessions (typical for transaction data). Note also: the use of the term "session" across CDS means the start and end of curb usage of a vehicle, not necessarily a financial or payment session or transaction.
`curb_zone_id`	UUID	Conditionally Required	Unique ID of the Curb Zone where the event occurred. Required for events that occurred in a known Curb Zone, if known and used, for ALL event_types.
`curb_area_ids`	Array of UUID	Conditionally Required	Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area, if known and used, for ALL event_types.
`curb_space_id`	UUID	Conditionally Required	Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space, if known and used, for ALL event_types.
`curb_object_id`	UUID	Conditionally Required	Unique ID of the Curb Object where the event occurred. Required for events that occurred at a known Curb Object, if known and used, for ALL event_types.
`data_source_type`	Enum Source Type	Required	General category of the source creating the event.
`data_source_operator_id`	UUID	Conditionally Required	Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, or the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the data_source_operators.csv file, and optional for others. Read our How to Get a Data Source Operator ID guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field, otherwise this field is required.
`data_source_operator_name`	String	Optional	Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discretion of the city.
`data_source_device_id`	UUID	Required	Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. If this field is needed for your use cases, review our Privacy Guidance.
`data_source_device_name`	String	Conditionally Required	Unique name of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is usually the internal ID they use for the device. Must be provided if the device has a visible or shared identifier. If this field is needed for your use cases, review our Privacy Guidance.
`data_source_manufacturer`	String	Optional	Manufacturer of the data source hardware or vehicle reporting event data.
`data_source_model`	String	Optional	Model of the data source hardware or vehicle reporting event data.
`sensor_status_is_commissioned`	Boolean	Optional	If a sensor was used to capture this event, the commissioned status at the time that the event was reported. Indicates whether the sensor is currently in a state where it should be reporting data.
`sensor_status_is_online`	Boolean	Optional	If a sensor was used to capture this event, the online status at the time that the event was reported. Indicates whether the sensor is currently online and reporting data.
`vehicle_id`	String	Optional	A vehicle identifier visible externally on the vehicle itself. If this field is needed for your use cases, review our Privacy Guidance. Note: in the next breaking CDS release, it is likely all of these "vehicle" fields will be moved to a Vehicles data object._
`vehicle_license_plate`	String	Optional	The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obfuscation, and security. If this field is needed for your use cases, review our Privacy Guidance. The detection of stealth, invisible, modified, ghost, or otherwise ANPR-evading plate violations may be recorded using the `enforcement` field and associated Enforcement object.
`vehicle_license_plate_jurisdiction`	String	Optional	Jurisdiction or state in which the `vehicle_license_plate` is registered.
`vehicle_license_plate_confidence`	Integer	Optional	Value from 1 to 100 specifying the recognition confidence level for `vehicle_license_plate`.
`vehicle_permit_number`	String	Optional	If applicable, the assigned permit number for this vehicle from the city agency.
`vehicle_length`	Integer	Conditionally Required	Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length.
`vehicle_type`	Vehicle Type	Conditionally Required	Type of the vehicle that performed the event. Required for sources capable of determining vehicle type.
`vehicle_type_confidence`	Integer	Optional	Value from 1 to 100 specifying the recognition confidence level for `vehicle_type`.
`vehicle_color`	String	Optional	Color of the vehicle that performed the event.
`vehicle_color_confidence`	Integer	Optional	Value from 1 to 100 specifying the recognition confidence level for `vehicle_color`.
`vehicle_company_name`	String	Optional	Company or courier name of the vehicle that performed the event.
`vehicle_company_name_confidence`	Integer	Optional	Value from 1 to 100 specifying the recognition confidence level for `vehicle_company_name`.
`vehicle_run_id`	String	Optional	Run identifier from an external runs table containing information about make, model, and/or year, of the vehicle that performed the event.
`vehicle_run_id_confidence`	Integer	Optional	Value from 1 to 100 specifying the recognition confidence level for `vehicle_run_id`.
`vehicle_propulsion_types`	Array of Propulsion Type	Conditionally Required	List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type.
`vehicle_blocked_lane_types`	Array of Lane Type	Conditionally Required	Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for sources capable of determining it for the following event_types: park_start
`curb_occupants`	Array of Curb Occupant	Conditionally Required	Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for sources capable of determining it for the following event_types: park_start, park_end, scheduled_report
`actual_cost`	Integer	Optional	If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. The currency type is sent in with the REST Endpoints JSON object. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents).
`enforcement`	Enforcement	Optional	Enforcement information related to this Curb Event, relevant to the moment in time the event happens. Only used for enforcement related events such as `vehicle_detected`, `vehicle_violation_start`, `vehicle_violation_end`, and `citation_issued`.
`payment_channel`	Payment Channel	Conditionally Required	If available from the source, the medium by which a user submitted payment.
`payment_method`	Payment Method	Conditionally Required	If available from the source, the method used to pay for this event.
`payment_transaction_id`	String	Conditionally Required	The transaction ID of the payment if available from the source and different from the `event_id`.
`custom_attributes`	Custom Attributes JSON Object	Optional	Additional attributes (fields and data) to include in this endpoint.
`external_references`	Array of External Reference objects	Optional	One or more references to external data sources impacting this Curb Event. The external reference is relevant to the moment in time the event happens.

Name	Description
`comms_lost`	Communications with the event source were lost
`comms_restored`	Communications with the event source were restored
`decommissioned`	Event source was decommissioned
`park_start`	A vehicle stopped, parked, or double parked
`park_end`	A parked vehicle leaving a parked or stopped state and resuming movement
`scheduled_report`	Event source reported status at a scheduled interval
`enter_area`	Vehicle enters the relevant geographic area. This differs from `vehicle_detected` since `enter_area` represents the tracking of a vehicle crossing the geo-boundary of an area/location.
`exit_area`	Vehicle exits the relevant geographic area
`vehicle_detected`	Detection or observation of a vehicle within or near a curb zone. Can originate from manual surveying, automated license plate recognition (LPR) systems, or other detection methods. This differs from the `enter_area` and `exit_area` events where a `vehicle_detected` event does not require the vehicle to be crossing the geo-boundary of an area/location.
`vehicle_violation_start`	Start of a compliance violation at a curb location, triggered when a vehicle is not permitted or has exceeded allowed time limits. This event may be published after detecting a vehicle but does not require a `vehicle_detected` event.
`vehicle_violation_end`	Resolution of a compliance violation, when the vehicle is no longer in violation of regulations. Used for time-based violations where the end of the violation can be detected. Requires a preceding `vehicle_violation_start` event for the same vehicle.
`citation_issued`	Issuance of a ticket or citation to a vehicle. May be published in addition to a related `vehicle_violation_start` event.

Name	Description
`data_feed`	Directly from a provider data feed sent to the agency
`camera`	Video or static image processing source
`above_ground`	Sensor deployed above ground
`in_ground`	Sensor deployed in the ground
`meter`	A smart parking meter
`payment`	From payment system or app
`in_person`	An individual on site recording the event digitally or otherwise
`other`	Sources not enumerated above

Name	Description
`bicycle`	A two-wheeled mobility device intended for personal transportation that can be operated via pedals, with or without a motorized assist (includes e-bikes, recumbents, and tandems)
`bus`	A vehicle larger than a car or small truck capable of transporting multiple passengers at once
`cargo_bicycle`	A two- or three-wheeled bicycle intended for transporting larger, heavier cargo than a standard bicycle (such as goods or passengers), with or without motorized assist (includes bakfiets/front-loaders, cargo trikes, and long-tails)
`car`	A passenger car or similar light-duty vehicle
`delivery_robot`	A robot or remote-operated device intended for transporting goods
`scooter`	A standing or seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles
`scooter_standing`	A standing fully-motorized mobility device without a seat intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles
`scooter_seated`	A fully-motorized mobility device with a seat intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles
`moped`	A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic
`motorcycle`	A seated mobility device capable of travel at high speeds and suited for operation in general urban traffic or expressways
`truck`	A box truck or large delivery truck with attached cab
`van`	A van with significant interior cargo space
`freight`	A large delivery truck with attached cab
`other`	A device that does not fit in the other categories
`unspecified`	Unspecified

Name	Description
`human`	Pedal or foot propulsion
`electric_assist`	Provides electric motor assist only in combination with human propulsion - no throttle mode
`electric`	Powered by battery-powered electric motor with throttle mode
`combustion`	Powered by gasoline combustion engine
`combustion_diesel`	Powered by diesel combustion engine
`hybrid`	Powered by combined combustion engine and battery-powered motor
`hydrogen_fuel_cell`	Powered by hydrogen fuel cell powered electric motor
`plug_in_hybrid`	Powered by combined combustion engine and battery-powered motor with plug-in charging

Name	Description
`construction`	Construction of hard assets including buildings and roadside infrastructure
`delivery`	General delivery of parcels, goods, freight
`emergency_use`	Includes ambulance, fire truck, police
`parking`	Vehicle parking, charging, or stopping
`passenger_transport`	Picking up and/or dropping off of human passengers
`special_events`	Includes unloading equipment for concerts, theatre, street events
`waste_management`	Retrieval/disposal of waste
`device_maintenance`	Includes scooter pickup, drop off, battery swapping
`autonomous`	Autonomous vehicle use
`ems`	Emergency medical vehicle use
`fire`	Emergency fire vehicle
`food_delivery`	Delivery of food items ready for consumption to an end consumer
`parcel_delivery`	Delivery of parcels, including bulk food goods to a restaurant or other business
`police`	Use by a police vehicle
`public_transit`	Includes large or small buses or paratransit.
`ride_hail`	Includes privately run ride hailing services
`road_maintenance`	Includes pothole patching, striping, snow plowing, street sweeping
`service_vehicles`	Includes private sector activity like some utilities
`taxi`	Traditionally licensed taxi services
`utility_work`	Includes public sector activity like sewer, water, telecoms
`vehicle_charging`	Parking for electric vehicles to charge
`vehicle_parking`	Includes private or commercial vehicle free or paid/metered parking
`vending`	Mobile vending or food truck curb uses
`unspecified`	Unknown or unspecified activity type

Name	Description
`meter`	User paid at a physical meter.
`mobile_app`	Paid via a mobile app, including iOS App Clips, and Android Instant App.
`sms`	Paid via text message.
`telephone`	Paid via a telephone call.
`website`	User went to a standard website to pay, maybe directed by QR code.
`other`	Some payment channel not captured above (please submit a pull request!).

Name	Description
`cash`	Bills or coins at a meter.
`credit_card`	Visa, Mastercard, etc at a meter.
`digital_wallet`	Payment disbursed from a digital wallet such as Apple Pay, Google Pay, Cash App, PayPal, or Venmo, etc. `credit_card` is preferred if the payment is made from a credit card via a digital wallet.
`smart_card`	A specialized smart card.
`membership_card`	A card used at a meter to pay via a corporate membership or loyalty program, etc.
`billing`	Curb user will be billed for usage at a later time.
`permit`	Curb user has a permit allowing them to use the curb without payment.
`voucher`	Curb user paid with a pre-issued voucher.
`courtesy`	At a curb that normally requires payment this event for some reason did not.
`test`	This was a test payment/event.
`other`	Some payment method not captured above (please submit a pull request!).

Name	Type	Required/Optional	Description
`type`	Vehicle Type	Required	The vehicle type of the occupant. When the event source is not capable of distinguishing vehicle type, this property must take the value "unspecified".
`length`	Float	Conditionally required	The approximate length in centimeters of the vehicle. Required when the event source is capable of determining vehicle length.
`linear_location`	Array of Float	Conditionally required	A two-element array that specifies the start and end of the occupant’s linear location relative to the start of the Curb Zone in that order. Required when the event source is capable of determining the linear location of occupants.