rahulyhg / geodesics

A toy web service using Flask

Geodesics

Synopsis

This is a toy web app that I wrote using Python/Flask as part of a job application. It consists of a web service and web page that calculates the geodesic distance between the user's location and another, fixed, location (in this case, White Bear Yard at 144A Clerkenwell Road, London, EC1R 5DF, UK).

Technologies Used

• Python
• Flask
• Requests
• Google Maps Geocoding API
• HTML5
• JavaScript
• jQuery

Requirements

The following libraries are required to run the web service:

• Python (see the website for installation instructions)
• Flask (easy_install flask to install in your environment)
• Requests (easy_install requests to install in your environment)

The end user is expected to be using a modern W3C compliant browser that supports the W3C geolocation specifications. My personal favourite is Google Chrome.

Setup

Having downloaded/cloned this project, beginning by edit the server settings in the geodesics.py file. In particular, change the following variables:

• HOST: the domain name or IP address for the web service.
• PORT: the port for the web service.
• DEBUG_MODE: whether or not debug mode is switched on.

Then, in the example.html file, edit the url variable in the getDistance JavaScript function (line 56) to have the same domain name and port number.

Local deployment

In a terminal window, navigate to the directory containing this project and then execute, python geodesics.py, in order to run the web service.

Then, in another terminal window, in the project directory, execute, python -m SimpleHTTPServer, to begin a web server. This will inform you where the HTTP server is being served eg. Serving HTTP on 0.0.0.0 port 8000 ... Navigate to the example.html file using the associated URL in your browser (eg. http://0.0.0.0:8000/example.html) to view the web page.

Remote deployment

The Flask documentation has some good tutorials about how to deploy a Flask web app (here and here) on your particular web server environment.

Usage

Request

The web service presents a single API endpoint which can be called with a GET HTTP method:

http://www.example.com/geodesics

This is called with the following parameters:

Parameter	Example	Details
q	Google Campus, London	required A query string containing a location. This could be a latitude and longitude pair separated by a comma, or an address. This will be geocoded by the Google Maps Geocoding API so it may be a fairly general address.
u	miles	optional A keyword which indicates the units for the resulting query. This may be one of km, m, miles or yards. If it is not one of these, or this keyword is ommited, the result defaults to km.

Thus an example request may be something like:

http://www.example.com/geodesics?q=Google%20Campus%2C%20London&u=miles

Note: it's always a good idea to URL escape characters in the parameter strings.

Response

The web service responds with a JSON response such as:

{
    "status":
    {
        "message": ...,
        "code": ...
    },
    "result":
    {
        "distance": ...,
        "elapsed": ...,
        "units": ...,
        "address": ...,
        "lat": ...,
        "lng": ...
    }
}

where each field is as follows:

Field	Details
message	Message associated with status of response.
code	HTTP response code.
distance	Geodesic distance between queried address and your fixed location (ie. White Bear Yard).
elapsed	Number of milliseconds required to process query. This does not include the transit time for sending the request or receiving the response.
units	Physical units of the distance value.
address	Formatted address of the queried address.
lat	Latitude of the queried address.
lng	Longitude of the queried address.

License

This project is licensed under the terms and conditions of The MIT License. Please see the license.txt file for more details.