Geolocation Service

• geolocation-service is a Java Restful Play Framework Application
• This application provides endpoints to retrieve geo locations for addresses stored in file addresses.conf. (/geolocation-service/conf/addresses.conf).

Getting Started

See instructions for retrieving the source code, start the application and information on how to interact with the api's. You should be able to start the application locally and test the various api's.

Prerequisites

Install the following:

Git
SBT

Getting Restful Application Up and Running

Instructions:

1. Clone Project or extract
2. Change Directory to project directory
3. Start Play Application with default port.
4. Health Check

1. git clone git@github.com:arcalderon/geolocation-service.git or extract geolocation-service.zip
2. cd geolocation-service
2. sbt run 
3. Health Check Url: http://localhost:9000/v1/geolocation-service

Interacting with the Application

• Running via Main Program - /geolocation-service/app/main/GeolocationServiceRunner.java - Not that for this interaction, the play application does not need to be started.
• Calling API with browser (see below)
• Curl Commands (see below)

Calling API with browser:

GET Get All Addresses

http://localhost:9000/v1/geolocation-service/addresses

Curl Commands:

Get All Addresses

curl --request GET --url http://localhost:9000/v1/geolocation-service/addresses

Sample Response

{
    status: 200,
    result: {
        addressResponses: [
            {
                address: "411 Brockton Ave, Abington, MA 02351, USA",
                status: "FOUND",
                location: {
                    lat: 42.100856,
                    lng: -70.9595332
                 }
            },
            {
                address: "Invalid Address",
                status: "NOT_FOUND",
                location: null
                }
            ]
       },
    errors: [ ]
}

Assumptions

Retry Logic

Number of retries is supplied in configuration file under key retries= 5. The retry number represents the number of times it will actually "retry", as oppose to the actual number of times it was actually invoked. Hence, the number of invocations are # of retry + 1 when a geolocation is not returned.

What constitutes as a "unable to find geolacation" ? It is when the response it self does not contain any geolocation information, for example, a response as such:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

For that matter also when perhaps an over rate-limit response occurs as such:

{
   "error_message" : "You have exceeded your rate-limit for this API.",
   "results" : [],
   "status" : "OVER_QUERY_LIMIT"
}

When either of the two scenarios above occurs the application initiates a retry effort. If retries are exhausted then it returns:

{
    status: 200,
    result: {
        addressResponses: [
            {
                address: "Invalid Address",
                status: "NOT_FOUND",
                location: null
                }
            ]
       },
    errors: [ ]
}

Rate Limiter

The rate limiter will be handled in a static fashion as oppose to dynamically. It will be assumed that the number of api calls per second has been established and known ahead of time as an SLA.

It could have been done dynamically if the response contained:

1.http status code of 429

2.header information such as a "Retry-After" suggesting how long to wait before making a new request.

The googleapis API returns 200 http status code even when rate-limit is reached.

JSON output In regards to the "address" attribute in the final JSON output, the actual value will be the value of the attribute "formatted_address" in the response of the api call and not the one provided in the addresses.conf file.