---
title: "Get Geo Suggestions"
method: GET
path: "/v1/geo-suggestions"
tags: ["Reference Data", "Companies", "v1"]
---

# Get Geo Suggestions

`GET /v1/geo-suggestions`

Resolves a typed city name or postal code into geographic coordinates. The returned `latitude` / `longitude` can be used to populate the `value.lat` / `value.lon` of the Geo Filter (`field: geo`, `operator: within`). Results can be scoped to one or more countries via `country_codes`, and `search_fields` limits which address fields the text may match; when omitted, both cities and postal codes are searched.

Credit Note: This endpoint does not consume credits.

:::info
Requires the `companies:read` OAuth2 scope.
:::

## Query parameters

- `account_id` string, required
- `search` string, required
- `search_fields` string[]
- `country_codes` string
- `page[size]` integer

## Response `200`

Matching location suggestions

- object
  - `data` GeoSuggestionV1[], required
    - `type` 'geo_suggestion', required
    - `id` string, required — A response-scoped UUID. It's new on every request — do not cache or persist it.
    - `attributes` object, required
      - `city` string, required — City name.
      - `postal_code` string, nullable — Postal code of the suggested location, when the match is a postal-code area. `null` for city-level matches.
      - `country_code` string, required — ISO-3166-1 alpha-2 country code.
      - `latitude` number, double, required — Latitude of the suggested location.
      - `longitude` number, double, required — Longitude of the suggested location.
  - `meta` object, required
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Missing or invalid query parameter
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `503` — Service unavailable
- `504` — Server timeout

---

[API](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/3b95d5a53148/schema)