geocoder.proto

syntax = "proto3";

package geocoder.v1;

// Geocoding service. Mirrors the REST API (/reverse, /search, /validate,
// /autocomplete, /geocode/ip). Message shapes match the JSON responses
// field-for-field so clients that currently consume the REST endpoints
// get the same data via gRPC without translation.
service Geocoder {
  rpc Reverse(ReverseRequest) returns (AddressResponse);
  rpc Search(SearchRequest) returns (SearchResponse);
  // Hard-radius "what's near me". Distinct from Search: lat/lng/
  // radius_km are required, results are sorted by distance ascending,
  // and anything outside the radius is dropped (not soft-penalised).
  rpc Nearby(NearbyRequest) returns (NearbyResponse);
  rpc Validate(ValidateRequest) returns (ValidateResponse);
  rpc Autocomplete(AutocompleteRequest) returns (AutocompleteResponse);
  rpc IpGeocode(IpGeocodeRequest) returns (IpGeocodeResponse);
  // Pure (lat, lon) → H3 cell map. Skips reverse-geocoding entirely;
  // resolves in microseconds. Use this when the client only needs the
  // H3 cell IDs for spatial joins and doesn't care about the address.
  rpc H3(H3Request) returns (H3Response);
}

// --- Shared types ---

message AddressDetails {
  string house_number = 1;
  string road = 2;
  string city = 3;
  string state = 4;
  string county = 5;
  string postcode = 6;
  string country = 7;
  string country_code = 8;
}

message Address {
  string display_name = 1;
  AddressDetails address = 2;
  // "exact" | "interpolated" | "fallback"
  string confidence = 3;
  // H3 cell IDs keyed by resolution; populated when the request
  // supplied `h3_res`. Empty map when no enrichment was requested.
  map<uint32, string> h3 = 4;
}

// --- /reverse ---

message ReverseRequest {
  double lat = 1;
  double lon = 2;
  // ISO 639-1 language preference for returned names. Accepted today;
  // honoured once the OSM builder emits name:<lang> tags.
  string lang = 3;
  // Optional H3 resolutions (0–15) to stamp on the response coord.
  // Empty = no enrichment; max 4 entries.
  repeated uint32 h3_res = 4;
}

message AddressResponse {
  Address address = 1;
}

// --- /search ---

message SearchRequest {
  string q = 1;
  string street = 2;
  string housenumber = 3;
  string city = 4;
  string state = 5;
  string country_code = 6;
  // "place" or "street"; empty = no filter
  string kind = 7;
  // 1..=50, defaults to 10 if 0.
  uint32 limit = 8;
  // Optional H3 resolutions (0–15) stamped on every hit. Max 4.
  repeated uint32 h3_res = 9;
  // Optional proximity bias for ambiguous-name disambiguation. When
  // both fields are present, hits are re-ranked so geographically-
  // close matches outrank far ones at similar BM25 scores. Both
  // MUST be supplied together; supplying only one returns
  // InvalidArgument. Range: lat ∈ [-90, 90], lng ∈ [-180, 180].
  // Skips the FST fast-path. See docs/SDK_PATTERNS.md for client-
  // side patterns to source the coord (browser geolocation, mobile
  // GPS, IP→coord chain through /geocode/ip).
  //
  // Uses proto3 `optional` so Null Island (0, 0) is a valid bias —
  // distinguishing "set to zero" from "not set" is semantically
  // important here.
  optional double bias_lat = 10;
  optional double bias_lng = 11;
}

message SearchHit {
  string name = 1;
  uint32 kind = 2;
  uint32 rank = 3;
  float score = 4;
  double lat = 5;
  double lon = 6;
  string display_name = 7;
  AddressDetails address = 8;
  // H3 cell IDs keyed by resolution; populated when the request
  // supplied `h3_res`. Empty map when no enrichment was requested.
  map<uint32, string> h3 = 9;
}

message SearchResponse {
  repeated SearchHit results = 1;
}

// --- /nearby ---

message NearbyRequest {
  // Centre point. Required. lat ∈ [-90, 90], lng ∈ [-180, 180].
  double lat = 1;
  double lng = 2;
  // Hard radius. Required. Must be > 0 and ≤ 100. Anything outside
  // is dropped from the response.
  double radius_km = 3;
  // Optional freeform text filter. When set, only hits whose text
  // matches (BM25 against name) AND fall inside the radius are
  // returned. Empty/absent ⇒ all hits in the radius (filtered by
  // kind / country_code).
  string q = 4;
  // Optional kind filter: "place", "street", or "poi".
  string kind = 5;
  // Optional country_code restriction (single ISO 3166-1 alpha-2,
  // case-insensitive).
  string country_code = 6;
  // 1..=50, defaults to 10 if 0.
  uint32 limit = 7;
  // Optional H3 resolutions (0–15) stamped on every hit. Max 4.
  repeated uint32 h3_res = 8;
}

message NearbyHit {
  string name = 1;
  uint32 kind = 2;
  uint32 rank = 3;
  double lat = 4;
  double lon = 5;
  // Distance from the request centre in metres. Pre-computed by the
  // server so callers don't need to re-do haversine.
  double distance_m = 6;
  string display_name = 7;
  AddressDetails address = 8;
  // H3 cell IDs keyed by resolution; populated when the request
  // supplied `h3_res`.
  map<uint32, string> h3 = 9;
}

message NearbyResponse {
  // Sorted by `distance_m` ascending.
  repeated NearbyHit results = 1;
}

// --- /validate ---

message ValidateRequest {
  string housenumber = 1;
  string street = 2;
  string city = 3;
  string state = 4;
  string postcode = 5;
  string country_code = 6;
  // Optional H3 resolutions (0–15) stamped on the response coord. Max 4.
  repeated uint32 h3_res = 7;
}

message ValidateResponse {
  bool verified = 1;
  string confidence = 2;
  double lat = 3;
  double lon = 4;
  Address normalized = 5;
  // H3 cell IDs keyed by resolution; populated when the request
  // supplied `h3_res`. Empty map when no enrichment was requested.
  map<uint32, string> h3 = 6;
}

// --- /autocomplete ---

message AutocompleteRequest {
  string q = 1;
  string country_code = 2;
  uint32 limit = 3;
  // Optional H3 resolutions (0–15) stamped on every hit. Max 4.
  repeated uint32 h3_res = 4;
}

message AutocompleteHit {
  string name = 1;
  string suburb = 2;
  uint32 kind = 3;
  uint32 rank = 4;
  double lat = 5;
  double lon = 6;
  // H3 cell IDs keyed by resolution; populated when the request
  // supplied `h3_res`. Empty map when no enrichment was requested.
  map<uint32, string> h3 = 7;
}

message AutocompleteResponse {
  repeated AutocompleteHit results = 1;
}

// --- /geocode/ip ---

message IpGeocodeRequest {
  // Textual IPv4 or IPv6. Empty = server uses the peer address.
  string ip = 1;
  // Optional H3 resolutions (0–15) stamped on the response coord. Max 4.
  repeated uint32 h3_res = 2;
}

message IpGeocodeResponse {
  string ip = 1;
  double lat = 2;
  double lon = 3;
  Address address = 4;
  // H3 cell IDs keyed by resolution; populated when the request
  // supplied `h3_res`. Empty map when no enrichment was requested.
  map<uint32, string> h3 = 5;
}

// --- /h3 ---
//
// Pure (lat, lon) → H3 cell-map computation. No reverse-geocoding,
// no admin lookup, no I/O — resolves entirely in h3o on the input
// coord. Same H3 enrichment shape as the other RPCs but standalone,
// for clients that only need spatial-join keys.

message H3Request {
  double lat = 1;
  double lon = 2;
  // Required: at least one resolution. Max 4 entries; each must be
  // 0..=15. Unlike the enrichment field on other RPCs, an empty list
  // is rejected here because the call has no other purpose.
  repeated uint32 h3_res = 3;
}

message H3Response {
  // Echo of the request coord — useful for batched calls where the
  // client wants to correlate response → request without tracking
  // the input separately.
  double lat = 1;
  double lon = 2;
  // H3 cell IDs keyed by resolution. Always populated for at least
  // one resolution (the call would have errored otherwise).
  map<uint32, string> h3 = 3;
}