Reverse geocoding served over gRPC, written in Scala. Location data is obtained from Geonames.
Reverse geocoding is the process of back (reverse) coding of a point location (latitude, longitude) to a readable address or place name. [Wikipedia]
The API is defined in reverse-geocoder.proto:
service ReverseGeocoder {
rpc ReverseGeocodeLocation (ReverseGeocodeLocationRequest) returns (ReverseGeocodeLocationResponse) {};
}
message ReverseGeocodeLocationRequest {
double latitude = 1;
double longitude = 2;
}
message ReverseGeocodeLocationResponse {
// Empty if none found
Place place = 1;
}
message Place {
string name = 1;
string country_code = 2;
double latitude = 3;
double longitude = 4;
uint32 elevation_meters = 5;
string timezone = 6;
uint64 population = 7;
google.protobuf.Timestamp sunrise_today = 8;
google.protobuf.Timestamp sunset_today = 9;
}
make docker
By default, the Docker image will download and use the cities500.zip data file from Geonames.
The easiest way to run reverse-geocoder is using Docker:
docker run -d vyshane/reverse-geocoder
You then can make a test request to the service using grpcurl. The application serves the reverse geocoder gRPC service on port 8080.
grpcurl -plaintext \
-proto src/main/protobuf/reverse-geocoder.proto \
-d '{"latitude": -20.2664803, "longitude": 57.4679569}' \
localhost:8080 \
mu.node.reversegeocoder.ReverseGeocoder/ReverseGeocodeLocation
Sample output of above call, in JSON format:
{
"place": {
"name": "Quatre Bornes",
"countryCode": "MU",
"latitude": -20.26381,
"longitude": 57.4791,
"timezone": "Indian/Mauritius",
"population": 80961,
"sunriseToday": "2018-11-13T01:23:08Z",
"sunsetToday": "2018-11-13T14:25:42Z"
}
}
reverse-geocoder will report health and readiness on port 3401 via HTTP, at /health and /readiness respectively. You can poll /readiness during startup to know when reverse-geocoder is ready to be added to your load balancer.
❱ curl -i http://localhost:3401/readiness master
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Date: Tue, 13 Nov 2018 13:48:52 GMT
Connection: keep-alive
Content-Length: 5
Ready%
reverse-geocoder can be configured through the following environment variables.
Environment Variable | Default Value |
---|---|
GRPC_PORT | 8080 |
STATUS_PORT | 3401 |
PLACES_FILE_PATH | N/A |