> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grdd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Fleet Search (Connect API)

> Search fleet vehicles near a map position with the Connect API service endpoint GET /api/fleets/search.

## 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.

<Note>
  This endpoint is **not** the same as [Fleet Search on core](/connect-api/fleet-search) (`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.
</Note>

### Base URL

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

```bash theme={null}
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](/connect-api/get-token).

```
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](/connect-api/fleet-search).

***

## 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](/connect-api/fleet-search) 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`.

<Warning>
  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`.
</Warning>

### 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.

<Warning>
  `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.
</Warning>

***

## Example request

```bash theme={null}
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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.