syntax = "proto3";
package opengeocoding.v1;

service OpenGeocoding {
  rpc Search(SearchRequest) returns (FullAddress) {}
  rpc Autocomplete(AutocompleteRequest) returns (AutocompleteResponse) {}
  rpc Retrieve(RetrieveRequest) returns (RetrievedSuggestion) {}
  rpc Reverse(ReverseRequest) returns (ReverseResponse) {}
  rpc Regions(RegionsRequest) returns (RegionsResponse) {}
  rpc ResolveRegion(GeoCoordinates) returns (RegionsResponse) {}
}

message RegionsRequest {}

message SearchRequest {
  string address_string = 1;
}

message ISO3166_2 {
  uint32 admin_level = 1;
  string code = 2;
}

message AddressDetails {
  string continent = 1;
  string country = 2;
  string country_code = 3;
  string region = 4;
  string state = 5;
  string state_district = 6;
  string county = 7;
  repeated ISO3166_2 region_codes = 8;
  string municipality = 9;
  string city = 10;
  string town = 11;
  string village = 12;
  string city_district = 13;
  string district = 14;
  string borough = 15;
  string suburb = 16;
  string subdivision = 17;
  string hamlet = 18;
  string croft = 19;
  string isolated_dwelling = 20;
  string neighbourhood = 21;
  string allotments = 22;
  string quarter = 23;
  string city_block = 24;
  string residential = 25;
  string farm = 26;
  string farmyard = 27;
  string industrial = 28;
  string commercial = 29;
  string retail = 30;
  string road = 31;
  string house_number = 32;
  string house_name = 33;
  string emergency = 34;
  string historic = 35;
  string military = 36;
  string natural = 37;
  string landuse = 38;
  string place = 39;
  string railway = 40;
  string man_made = 41;
  string aerialway = 42;
  string boundary = 43;
  string amenity = 44;
  string aeroway = 45;
  string club = 46;
  string craft = 47;
  string leisure = 48;
  string office = 49;
  string mountain_pass = 50;
  string shop = 51;
  string tourism = 52;
  string bridge = 53;
  string tunnel = 54;
  string waterway = 55;
  string postcode = 56;
  string province = 57;
  string highway = 58;
  repeated Region regions = 59;
}

message BoundingBox {
  float min_lat = 1;
  float max_lat = 2;
  float min_lon = 3;
  float max_lon = 4;
}

message GeoCoordinates {
  float lat = 1;
  float lon = 2;
  BoundingBox bounding_box = 3;
}

message FullAddress {
  string display_name = 1;
  GeoCoordinates geo_coordinates = 2;
  AddressDetails address_details = 3;
  bool good_match = 4;
}

message Region {
  string country_code = 1;
  string country_name = 2;
  string admin_code = 3;
  uint32 admin_level = 4;
  string local_name = 5;
  string en_name = 6;
  string parent_admin_code = 7;
}

message RegionsResponse {
  repeated Region regions = 1;
}

// Completes an address or place as it is typed: the last word of `text` may be unfinished.
message AutocompleteRequest {
  string text = 1;
  // Default 5, at most 15.
  uint32 limit = 2;
  // Optional ISO 3166-1 alpha-2 code: only suggestions in that country.
  string country_code = 3;
  // Optional: the user's position. Places near it rank higher.
  SuggestFocus focus = 4;
  // Also suggest landmarks (type "landmark"): airports, stations, attractions, museums,
  // universities, hospitals and stadiums that OpenStreetMap links to Wikidata. Default false.
  bool include_landmarks = 5;
}

// A place at the point weighs as if it were a thousand times as populous, one `scale_km` away
// about 500 times, ten `scale_km` away about 10 times.
message SuggestFocus {
  float lat = 1;
  float lon = 2;
  // Default 100, at most 20000.
  uint32 scale_km = 3;
}

message Suggestion {
  // Stable for one index, and opaque: a place, street, house, postcode or landmark.
  string id = 1;
  string display_name = 2;
  reserved 3;
  // country, region, county, municipality, city, town, village, neighbourhood, street, address,
  // postcode or landmark.
  string type = 4;
  string country_code = 5;
  // Landmarks only: airport, station, attraction, museum, university, hospital or stadium.
  // Empty for every other type.
  string category = 6;
  // User-entered floor/unit text, also kept in display_name. Not verified: id and point
  // still identify the building. Empty when no suffix interpretation was needed.
  string unverified_suffix = 7;
}

message RetrievedSuggestion {
  // Stable for one index, and opaque: a place, street, house, postcode or landmark.
  string id = 1;
  string display_name = 2;
  // The point of the place, street, house, postcode or landmark. Places also carry their
  // bounding box.
  GeoCoordinates geo_coordinates = 3;
  // country, region, county, municipality, city, town, village, neighbourhood, street, address,
  // postcode or landmark.
  string type = 4;
  string country_code = 5;
  // Landmarks only: airport, station, attraction, museum, university, hospital or stadium.
  // Empty for every other type.
  string category = 6;
  // User-entered floor/unit text, also kept in display_name. Not verified: id and point
  // still identify the building. Empty when no suffix interpretation was needed.
  string unverified_suffix = 7;
}

message RetrieveRequest {
  // Opaque ID returned by SuggestAddress. Valid only for the same index snapshot.
  string id = 1;
}

message AutocompleteResponse {
  repeated Suggestion suggestions = 1;
}

// The addresses nearest a point.
message ReverseRequest {
  float lat = 1;
  float lon = 2;
  // Search radius for addresses and streets, in meters. Default 500, at most 2000.
  uint32 radius_m = 3;
  // Default 1, at most 10.
  uint32 size = 4;
}

message ReverseResult {
  FullAddress address = 1;
  float distance_m = 2;
  // "address": a house within the radius. "street": no house was in range, so a street within
  // it, at its point nearest the given one. "locality": neither was in range, so the nearest
  // locality point, wherever it is within about 50 km.
  string layer = 3;
}

message ReverseResponse {
  // Nearest first. Empty when nothing is in range.
  repeated ReverseResult results = 1;
}