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

# Operator Search (Connect API)

> Search active GNet operator profiles with the Connect API service endpoint GET /api/search.

## Operator Search (Connect API)

`GET /api/search` finds active GNet operator (company) profiles. You can search by name, place, map position, vehicle type, service, and audit badge. Each result is a fixed, public summary of one operator.

<Note>
  This endpoint runs on the **Connect API service**, not on core. It is a different endpoint from [Search Members](/connect-api/search) (`GET /api/company/search` on core). The two take different parameters and return different fields. Do not swap them. See the [Search overview](/connect-api/search/overview).
</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/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. Tokens with the `gateway` role are service credentials. This endpoint does **not** accept them. It returns `401` for a `gateway` token.

***

## Query parameters

All parameters are optional. The service rejects any parameter that is not in this table with `400`. You can repeat only `vehicleType`, `service`, and `badge`. Any other parameter that occurs twice gives `400`.

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Operator name, up to 100 characters. Minimum length is 2 characters, or 1 if you also send `latitude` and `longitude`. |
| `latitude` | number | Search center latitude, from `-90` to `90`. Send it with `longitude`. |
| `longitude` | number | Search center longitude, from `-180` to `180`. Send it with `latitude`. |
| `radiusKm` | integer | Search radius in kilometers, from `1` to `3000`. Needs `latitude` and `longitude`. If you omit it, the service chooses a default from the place and scope. The default is not part of the contract. |
| `scope` | string | One of `country`, `state`, `city`, `airport`, `zip`. Sets how the service reads a place. Needs `latitude` and `longitude`, unless you also send `country`, `state`, `city`, or `zip`. |
| `country` | string | Country, 1–100 characters. |
| `state` | string | State or region, 1–100 characters. |
| `city` | string | City, 1–100 characters. |
| `zip` | string | Postal or zip code, 1–32 characters. |
| `coType` | string | Company type, 1–80 characters. |
| `vehicleType` | string, repeatable | Vehicle type the operator offers, up to 80 characters each. Up to 50 values. An operator matches if it offers any of the values. |
| `service` | string, repeatable | Service the operator offers, up to 80 characters each. Up to 50 values. An operator matches if it offers any of the values. |
| `badge` | string, repeatable | Audit badge, up to 40 characters each. Up to 50 values. Only some plans can use it. See [Plan limits](#plan-limits). |
| `sort` | string | One of `relevance`, `score`, `joinDate`, `sp`. Default: `relevance`. |
| `limit` | integer | Maximum results, from `1` to `300`. Default: `300`. See [Plan limits](#plan-limits). |
| `locale` | string | One of `en`, `es`, `de`, `fr`. Default: `en`. |

An empty value for a number parameter (for example `latitude=`) is invalid.

### Plan limits

The service limits what each caller can receive. These limits come from the account's plan.

| Account | Maximum results returned |
| - | - |
| `io` or `basic` plan | 20 |
| `professional`, `premium`, or `enterprise` plan | 300 |
| Active trial | 300 |

The service returns at most the smaller of `limit` and the plan limit. The `badge` filter works only for `premium` and `enterprise` plans. For other plans, the service **removes** `badge` and still runs the search. It does not return an error.

The service has no paging. It returns one ranked window of up to 300 candidates. `nextCursor` is always `null`.

***

## Example request

```bash theme={null}
curl "$CONNECT_API_BASE_URL/api/search?name=Acme&latitude=43.6532&longitude=-79.3832&radiusKm=60&vehicleType=sedan&vehicleType=suv&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

***

## Success response

**200 - OK**

```json theme={null}
{
  "items": [
    {
      "griddid": "acme",
      "conextid": "acme",
      "name": "Acme Limousine",
      "city": "Toronto",
      "state": "Ontario",
      "country": "Canada",
      "sp": 2,
      "coType": "CO",
      "logo_url": "https://assets.gogridd.com/acme/logo.png",
      "distance": 4.2,
      "tagline": "Service fiable",
      "relevanceScore": 80,
      "fleet": ["sedan"],
      "services": ["Airport Transfer"],
      "lat": 43.65,
      "lng": -79.38,
      "auditBadge": "gold",
      "auditBadgePlus": true,
      "matchedLocation": {
        "griddid": "acme",
        "slug": "acme-toronto",
        "city": "Toronto",
        "state": "Ontario",
        "lat": 43.65,
        "lon": -79.38,
        "distanceKm": 4.2
      },
      "locale": "fr",
      "resolvedLocale": "fr"
    }
  ],
  "totalFound": 1,
  "nextCursor": null
}
```

The response has no `success` field. The response headers include `Cache-Control: no-store` and `X-Correlation-Id`.

### Response fields

| Field | Type | Description |
| - | - | - |
| `items` | array | Matching operators. At most 300. |
| `totalFound` | integer | Number of matches before the plan limit and `limit` cut the list. |
| `nextCursor` | null | Always `null`. |

Each item in `items`:

| Field | Type | Description |
| - | - | - |
| `griddid` | string | GNet ID of the operator. |
| `conextid` | string / null | GNet ID as stored on the operator profile. Usually equal to `griddid`. |
| `name` | string | Operator name. |
| `city`, `state`, `country` | string / null | Operator place. `city` and `state` come from the matched location when the search used a map position. |
| `sp` | number | Operator plan value. |
| `coType` | string / null | Company type. |
| `logo_url` | string / null | Logo URL. |
| `distance` | number / null | Distance in km from the search center to the matched location. `null` if the search had no map position. |
| `tagline` | string / null | Operator tagline. |
| `relevanceScore` | number | Name match score. `0` if you did not send `name`. |
| `fleet` | string array | Vehicle types the operator offers. |
| `services` | string array | Services the operator offers. |
| `lat`, `lng` | number / null | Coordinates of the matched location, or of the operator. |
| `auditBadge` | `"gold"` / `"blue"` / null | Audit badge. |
| `auditBadgePlus` | boolean / null | Whether the operator has the badge-plus mark. |
| `matchedLocation` | object / null | The operator location that matched a map search: `griddid`, `slug`, `city`, `state`, `lat`, `lon`, `distanceKm`. `null` if the search had no map position. |
| `locale` | string | The `locale` you requested. |
| `resolvedLocale` | string | The language of the returned text. It can be `en` when no translation exists for the requested language. |

The service does not return contact details, credentials, trial data, or internal scores.

***

## Error responses

Errors use the `application/problem+json` content type:

```json theme={null}
{
  "code": "invalid_request",
  "message": "Request is invalid",
  "correlationId": "8e2f9ddf-47b3-4bfd-b2ec-2347f96e675f",
  "retryable": false,
  "fieldErrors": {
    "longitude": ["latitude and longitude must be supplied together"]
  }
}
```

`reason` and `fieldErrors` appear only when they apply. Use `correlationId` when you contact support.

| Status | `code` | When |
| - | - | - |
| `400` | `invalid_request` | A parameter is invalid, unknown, or repeated. `fieldErrors` names each field. |
| `401` | `unauthenticated` | The `Authorization: Bearer` header is missing, or core says the token is invalid or expired. The service also returns this for a `gateway` token. |
| `403` | `entitlement_denied` | The account is not allowed to search. |
| `503` | `temporarily_unavailable` | The service cannot verify the token with core, or the search data is 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.