Fleet Search (Connect API)

GET /api/fleets/search finds fleet vehicles near a latitude and longitude. The Connect API service sends the search to core and then adds verification and audit-badge data. It can also filter results by those fields.

This endpoint is not the same as Fleet Search on core (GET https://core.grdd.net/api/search/fleet). Differences:

It runs on the Connect API service, not on core.
It needs lat and lon. It does not accept airports.
It rejects unknown parameters.
It adds verified, interstate, and intrastate filters.
It adds verification and badge fields to each item.
It returns Connect API problem errors, not core’s {"success": false, "message": ...} errors.

Do not use one as a drop-in replacement for the other.

Base URL

The Connect API base URL is not published in these docs. Ask GRiDD support (support@grdd.net) for the Connect API base URL for your environment. The examples use a shell variable:

export CONNECT_API_BASE_URL="<base URL from GRiDD support>"

Endpoint

GET $CONNECT_API_BASE_URL/api/fleets/search

Authentication

Send a token that core issued. See the Get Token API.

Authorization: Bearer <access_token>

The Connect API service verifies the token with core. It then sends the same token to core’s GET /api/search/fleet as a Bearer token. Core’s rules for that endpoint therefore also apply to your request. This includes the page-size rule for accounts below the Professional plan. See Fleet Search on core.

Query parameters

lat and lon are required. The service rejects any parameter that is not in this table with 400. Each parameter can occur only once.

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude of the search center.
`lon`	number	Yes	Longitude of the search center.
`types`	string	No	Comma-separated vehicle types, for example `sedan,suv`. Core applies the filter.
`q`	string	No	Keyword. Core applies the filter. See Fleet Search on core for the matching rules.
`radius_km`	number	No	Search radius in kilometers. Core sets the default and checks the value.
`limit`	integer	No	Page size, from `1` to `100`.
`offset`	integer	No	Number of results to skip. `0` or more.
`verified`	`true` / `false`	No	If `true`, return only items with `isVerified` set to `true`.
`interstate`	`true` / `false`	No	If `true`, return only items whose `auditBadge` is `gold`.
`intrastate`	`true` / `false`	No	If `true`, return only items whose `auditBadge` is `blue`.

The boolean parameters accept only the text true or false. If you send interstate=true and intrastate=true, an item matches if its badge is gold or blue.

The service checks only that lat, lon, and radius_km are numbers. Core checks their ranges (for example lat from -90 to 90, and radius_km above 0). If core rejects a value, the Connect API service returns 502 with downstream_failure, not 400.

How the filters work

Core handles lat, lon, types, q, radius_km, limit, and offset.
The Connect API service handles verified, interstate, and intrastate. It does not send them to core.
When you use one of these three filters, the service asks core for a large first page (at least 1000 items, from offset 0). It filters that page and then applies your offset and limit itself. total is the number of items left after filtering.
Core still limits its own page size: to 100, or to 20 for accounts below the Professional plan. These filters can only see the items that core returns, so they can miss matches that are beyond that page.

verified=true depends on a vehicle id field in each item. The core Fleet Search item list in these docs has no id field. Based on the source, verified=true may return no items when core does not send an id. This is not confirmed against a running system. Test it with your own account before you rely on it.

Example request

curl "$CONNECT_API_BASE_URL/api/fleets/search?lat=43.6532&lon=-79.3832&radius_km=25&types=sedan&limit=50&offset=0&intrastate=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success response

200 - OK The body has the same envelope as core’s Fleet Search:

{
  "success": true,
  "data": {
    "items": [],
    "total": 0,
    "warnings": []
  }
}

The contract fixes only the envelope: data.items (array), data.total (integer), and data.warnings (array). It does not fix the fields of each item. Each item is an item from core’s Fleet Search. The service changes it as follows:

If an item has photo fields, it normalizes them and puts the photo URL in imageUrl.
It adds verificationDate (a number, or null), isVerified (boolean), auditBadge ("gold", "blue", or null), and auditBadgePlus (boolean).

Illustrative item (not a complete contract):

{
  "griddid": "acme-limo",
  "type": "sedan",
  "name": "Business Class Sedan",
  "imageUrl": "https://asset.grdd.dev/profile/acme-limo/business-class-sedan.png",
  "maxPassengers": 4,
  "maxLuggage": 2,
  "lat": 43.65,
  "lon": -79.38,
  "distanceKm": 1.23,
  "verificationDate": null,
  "isVerified": false,
  "auditBadge": "blue",
  "auditBadgePlus": false
}

The service adds the verification and badge fields only when the result has at least one item with a griddid.

200 with `success: false`

If core answers with a body that is not a successful fleet search, the service returns 200 with a failure body:

{
  "success": false,
  "message": "Search unavailable"
}

The message is core’s message when core sent one. Check success on every response.

Error responses

Errors use the application/problem+json content type. The body has code, message, correlationId, and retryable. fieldErrors appears when it applies.

{
  "code": "invalid_request",
  "message": "Request is invalid",
  "correlationId": "8e2f9ddf-47b3-4bfd-b2ec-2347f96e675f",
  "retryable": false,
  "fieldErrors": {
    "lat": ["Expected number, received nan"]
  }
}

Status	`code`	When
`400`	`invalid_request`	A required parameter is missing, a parameter is unknown, repeated, or not a valid value. `fieldErrors` names each field.
`401`	`unauthenticated`	The `Authorization: Bearer` header is missing, or core says the token is invalid or expired.
`403`	`forbidden` or `entitlement_denied`	The account is not allowed to use fleet search.
`502`	`downstream_failure`	The request to core’s `/api/search/fleet` failed, or core answered with an error status. `retryable` is `true`.
`503`	`temporarily_unavailable`	The service cannot verify the token with core, or access checks are not available. `retryable` is `true`. Retry later.

The service can also return 500 with internal_error for an unexpected failure.

Getting Started

Core Operations

Content

Search

Location

Fleet Search (Connect API)