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.

This endpoint runs on the Connect API service, not on core. It is a different endpoint from Search Members (GET /api/company/search on core). The two take different parameters and return different fields. Do not swap them. See the Search overview.

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/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. 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.
`sort`	string	One of `relevance`, `score`, `joinDate`, `sp`. Default: `relevance`.
`limit`	integer	Maximum results, from `1` to `300`. Default: `300`. See 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

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

{
  "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:

{
  "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.

Getting Started

Core Operations

Content

Search

Location

Operator Search (Connect API)