---
title: "Search for a location by free-text query"
method: GET
path: "/api/transactions/geocode"
tags: ["Transactions"]
---

# Search for a location by free-text query

`GET /api/transactions/geocode`

Free-text geocoding via OpenStreetMap Nominatim. Returns up to 5 candidates.

## Query parameters

- `q` string, required

## Response `200`

Geocoding candidates

- object
  - `results` object[], required
    - `displayName` string, required
    - `location` TransactionLocation, nullable, required
      - `address` string, nullable, required
      - `city` string, nullable, required
      - `country` string, nullable, required
      - `lat` number, nullable, required
      - `lon` number, nullable, required
      - `postal_code` string, nullable, required
      - `region` string, nullable, required
      - `store_number` string, nullable, required

## Other responses

- `401` — Unauthorized
- `403` — Subscription required
- `422` — Validation failed
- `502` — Geocoder upstream failed

---

[API](https://skmtc.net/cobaltpf/apis/cobalt-api.md) · [All operations](https://skmtc.net/cobaltpf/apis/cobalt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cobaltpf/cobalt-api/revisions/8ef0dfb5d23c/schema)