Flock Safety Plate Reads API
The Plate Reads API from Flock Safety — 2 operation(s) for plate reads.
OpenAPI Specification
openapi: 3.0.3
info:
title: Flock Safety API Platform (v3) Alerts Plate Reads API
description: Flock Safety v3 API Platform harvested from the public developer hub (docs.flocksafety.com). Combines the Device, Custom Hotlist, LPR Search, Plate Lookup, Hotlist Alerts Subscription, Geolocation, CAD, Inbound Alerts, and Vehicle Detections Ingest APIs. OAuth2 client_credentials (machine) and authorization_code (user) flows against api.flocksafety.com.
version: 3.0.0
contact:
name: Flock Safety Developer Hub
url: https://docs.flocksafety.com/
servers:
- url: https://api.flocksafety.com/api/v3
description: Production
- url: https://dev-api.flocksafety.com/api/v3
description: Development sandbox (at Flock discretion)
tags:
- name: Plate Reads
paths:
/reads/lookup/page/{pageId}:
get:
summary: View license plate reads lookup results
description: 'View the results of a license plate read lookup
## Required API scope
[plate-reads:lookup](https://docs.flocksafety.com/developer-hub/docs/client-credentials)
'
tags:
- Plate Reads
parameters:
- in: path
name: pageId
schema:
type: string
required: true
description: The ID of the page to view.
responses:
'200':
description: List of license plate reads
content:
application/json:
schema:
$ref: '#/components/schemas/LookupResult'
'401':
$ref: '#/components/responses/AuthorizationError'
'403':
$ref: '#/components/responses/UnauthorizedError'
'422':
description: The page ID is missing.
$ref: '#/components/responses/ValidationError'
'429':
description: The maximum number of requests you can perform per second has been exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Rate Limit Error:
$ref: '#/components/examples/RateLimitError'
/reads/lookup:
post:
summary: Lookup license plate reads
description: 'Look up license plate reads by full license plate characters.
## Required API scope
[plate-reads:lookup](https://docs.flocksafety.com/developer-hub/docs/client-credentials)
'
tags:
- Plate Reads
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupRequest'
responses:
'200':
description: List of license plate reads
content:
application/json:
schema:
$ref: '#/components/schemas/LookupResult'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthorizationError'
'403':
$ref: '#/components/responses/UnauthorizedError'
'422':
description: The given lookup criteria contain one or more errors.
$ref: '#/components/responses/ValidationError'
'429':
description: The maximum number of requests you can perform per second has been exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Rate Limit Error:
$ref: '#/components/examples/RateLimitError'
components:
schemas:
LookupRequest:
type: object
description: A request to lookup license plate reads.
required:
- plate
- reason
- startDate
- endDate
properties:
plate:
type: string
description: The license plate to lookup.
example: FNA579
startDate:
type: string
description: The beginning date range for the lookup. The specified date must be in ISO8601 format.
example: '2022-08-06T12:26:00.000Z'
format: date-time
endDate:
type: string
description: The end of the date range for the lookup. The specified date must be in ISO8601 format.
example: '2022-08-09T23:59:59.000Z'
format: date-time
limit:
type: number
minimum: 1
maximum: 50
description: The limit for the maximum number of reads that can be returned on a single page.
minConfidences:
type: array
items:
$ref: '#/components/schemas/ConfidenceFilter'
state:
type: string
enum:
- alabama
- alaska
- arizona
- arkansas
- california
- colorado
- connecticut
- delaware
- washington_dc
- florida
- georgia
- hawaii
- idaho
- illinois
- indiana
- iowa
- kansas
- kentucky
- louisiana
- maine
- maryland
- massachusetts
- michigan
- minnesota
- mississippi
- missouri
- montana
- nebraska
- nevada
- new_hampshire
- new_jersey
- new_mexico
- new_york
- north_carolina
- north_dakota
- ohio
- oklahoma
- oregon
- pennsylvania
- rhode_island
- south_carolina
- south_dakota
- tennessee
- texas
- utah
- vermont
- virginia
- washington
- west_virginia
- wisconsin
- wyoming
- puerto_rico
description: Filters results to where only plate from the specified state are returned.
reason:
type: string
description: 'The reason this plate reads lookup is being done. This is in place in order to ensure the system can be audited for misuse for customers.
'
example: 'Tracking vehicle involved with case #103024'
caseNumber:
type: string
description: The relevant case number for this lookup, if applicable.
example: '103024'
sort:
type: array
items:
$ref: '#/components/schemas/SortCriteria'
radius:
$ref: '#/components/schemas/RadiusFilter'
description: Optional raidus filter to apply to the lookup.
area:
$ref: '#/components/schemas/AreaFilter'
description: Optional area filter to apply to the lookup.
not:
required:
- radius
- area
example:
plate: FNA579
reason: 'Tracking vehicle involved with case #103024'
startDate: '2022-08-06T12:26:00Z'
endDate: '2022-08-09T23:59:59Z'
limit: 10
state: arkansas
caseNumber: '103024'
sort:
- field: capturedAt
order: desc
radius:
radius:
latitude: 40.783871
longitude: -73.97541
radius: 5
Network:
type: object
description: The network that the device belongs to.
required:
- id
- name
properties:
id:
type: string
description: The ID for the network
example: 72d97364-3f45-4e16-ae52-631aea3141cc
name:
type: string
description: The name of the network
example: Little Rock AR PD
LicensePlateRead:
type: object
description: A license plate read
required:
- id
- capturedAt
- device
- plate
properties:
id:
type: string
description: The ID that identifies this specific license plate read.
example: 4171ae2b-843f-405b-922d-b1e89921f24f
capturedAt:
type: string
description: The timestamp (in RFC3339 UTC format) indicating when the license plate was captured.
example: '2023-12-31T23:59:59.999999Z'
device:
description: The device that captured the license plate.
$ref: '#/components/schemas/Device'
state:
$ref: '#/components/schemas/StateInfo'
plate:
$ref: '#/components/schemas/PlateInfo'
link:
type: string
description: A link to view the license plate read within our UI.
example: https://share.flocksafety.com/lookup/33fc2d53-5b1e-4f9a-95b8-a3fe47823d26
ErrorResponse:
properties:
error:
type: string
Location:
properties:
name:
type: string
description: commmon name to identify location by
latitude:
type: number
longitude:
type: number
streetAddress:
type: string
city:
type: string
state:
type: string
country:
type: string
additionalMetadata:
$ref: '#/components/schemas/AdditionalMetadata'
description: either latitude and longitude is required, or one of streetAddress/city/state
SortCriteria:
type: object
properties:
field:
type: string
enum:
- capturedAt
description: The field to sort results by.
order:
type: string
enum:
- asc
- desc
description: "The order to sort by:\n * `asc` - Ascending, from the oldest to the newest.\n * `desc` - Descending, from the newest to the oldest.\n"
required:
- field
- order
Device:
type: object
required:
- id
- type
- name
- location
- network
- metadata
- createdAt
- modifiedAt
properties:
id:
type: string
description: The ID of the device.
type:
$ref: '#/components/schemas/DeviceType'
name:
type: string
description: The name of the device.
location:
$ref: '#/components/schemas/Location'
network:
$ref: '#/components/schemas/Network'
metadata:
type: object
description: Metadata about the device.
createdAt:
type: object
description: The timestamp (in RFC3339 UTC format) indicating when the image was captured.
example: '2023-12-31T23:59:59.999999Z'
modifiedAt:
type: object
description: The timestamp (in RFC3339 UTC format) indicating when the image was captured.
example: '2023-12-31T23:59:59.999999Z'
link:
type: string
description: A link to view the device in the Flock UI.
example: https://hotlist.flocksafety.com/dispatch/type/audio?id=00000000-0000-0000-000000000000
RadiusFilter:
type: object
description: Filters the results to where only reads captured within this radius will be returned.
properties:
radius:
type: object
properties:
latitude:
type: number
description: The latitude for the center-point of the radius.
example: 40.783871
longitude:
type: number
description: The longitude for the center-point of the radius.
example: -73.97541
radius:
type: number
minimum: 1
maximum: 2000
example: 5
description: The radius, in miles, of the circle around the centerpoint.
AdditionalMetadata:
type: object
properties:
type:
enum:
- string
- number
- boolean
description: What type the value of the metadata value is
value:
type: object
description: value of the metadata. Must be a string, number, or boolean
description: flat json object, defaults to {} and returned as {} if not provided
LookupResult:
type: object
description: Results
required:
- results
- totalItems
properties:
results:
type: array
description: List of license plate reads
items:
$ref: '#/components/schemas/LicensePlateRead'
nextPageId:
type: string
description: The ID of the next page. This ID is used in the [Get Results](#/paths/~1reads~1lookup/get) endpoint.
previousPageId:
type: string
description: The ID of the previous page. This ID is used in the [Get Results](#/paths/~1reads~1lookup/get) endpoint.
totalItems:
type: number
description: The total number of reads that are available to view.
example: 2
DeviceType:
type: string
description: The device's type.
enum:
- camera
- video
- audio
- external
StateInfo:
type: object
required:
- state
- confidence
properties:
state:
type: string
description: The state that the license plate is from.
example: arkansas
confidence:
type: number
description: A number expressing certainty in that the state was correctly identified. The range is between 0.0 and 1.0
example: 0.75
ConfidenceFilter:
type: object
required:
- attribute
- minConfidence
properties:
attribute:
type: string
enum:
- plate
- state
description: Specifies the attribute to which the confidence filter should be applied.
minConfidence:
type: number
minimum: 0
maximum: 1
example: 0.5
description: 'The minimum confidence threshold, expressed as a decimal between 0.0 and 1.0. This filter applies only to the specified attribute. Results where the confidence score for the specified attribute is below this value will be excluded.
'
AreaFilter:
type: object
description: 'Filters the results to where only reads captured within an area will be returned. The area must be defined as a [GeoJSON Polygon with a single ring](https://mapsam.com/geojson-ring-visual/).
'
properties:
area:
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Polygon
coordinates:
type: array
minItems: 1
maxItems: 1
items:
type: array
minItems: 4
items:
type: array
minItems: 2
maxItems: 2
items:
type: number
example:
type: Polygon
coordinates:
- - - 102
- 2
- - 103
- 2
- - 103
- 3
- - 102
- 3
- - 102
- 2
PlateInfo:
type: object
required:
- plate
- confidence
properties:
plate:
type: string
description: The license plate.
example: XNA357
confidence:
type: number
description: A number expressing certainty in that the license plate was correctly identified. The range is between 0.0 and 1.0
example: 0.9
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
oauth2Auth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.flocksafety.com/oauth/token
scopes:
custom-holists:read: Read access to custom hotlists
custom-holists:write: Write access to custom hotlists
FlockOAuth:
type: oauth2
description: OAuth 2 with the client credentials flow
flows:
clientCredentials:
scopes:
plate-reads:lookup: Access to perform lookups on license plate reads.
tokenUrl: https://api.flocksafety.com/oauth/token
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.flocksafety.com/oauth/token
scopes: {}