#Import modules
import requests
import json

"""
Explanation: Geocoding using the Open Street Map API
Here we explore an example of using an Application Programming Interface, or API. Briefly, an API is a set of commands we can send over the internet to a remote server, spurring the server to process these commands and return a response. In this example, we'll explore how we can use the Open Street Map's geocoding API to get the coordinates responding to a particular address.
This is not an in-depth exploration of this particular API, but rather an introduction on how to use an API within Python, specfically using the handy requests and json libraries. 

First we import the requests and json modules.<br>Usfeful documentation on these modules are found here: <br>
* requests: http://docs.python-requests.org
* json: https://pymotw.com/2/json/
End of explanation
"""


#Get the address
address = '9 Circuit Drive, Durham, NC, 27708' 

"""
Explanation: Now we will form the request to invoke the Open Street Map API. Documentation on this API is found here: 
http://wiki.openstreetmap.org/wiki/Nominatim
First, we'll generate an example address to geocode. Why not use Environment Hall? But feel free to use your own address!
End of explanation
"""


#Form the request
osmURL = 'http://nominatim.openstreetmap.org/search'
params = {'format':'json','q':address} 

"""
Explanation: An API request consists two components: the service endpoint and a set of parameters associated with the service. 
When using the requests module to create and send our request, we supply the service endpoint is a string containing the server address (as a URL) and the service name (here, it's search). And the parameters are supplied in the form of a Python dictionary. Here, the two paramters we'll pass are the format and address parameters.
End of explanation
"""


#Send the request
response = requests.get(osmURL, params)

"""
Explanation: Now, we can use requests to send our command off to the OSM server. The server's response is saved as the response variable.
End of explanation
"""


response.url

#Opens the URL as an html response (vs JSON) in a web browser...
import webbrowser
webbrowser.open_new(response.url.replace('json','html'))

"""
Explanation: The response object below contains a lot of information. You are encouraged to explore this object further. Here we'll explore one property which is the full URL created. Copy and paste the result in your favorite browser, and you'll see the result of our request in raw form. When you try this, try changing 'json' to 'html' in the URL...
End of explanation
"""


#Read in the response as a JSON encoded object
jsonObj = response.json()

"""
Explanation: What we really want from the response, however, is the data returned by the service. The json function of the response object converts the response to an object in JavaScript Object Notation, or JSON. JSON is esentially a list of dictionaries that we can easily manipulate in Python.
End of explanation
"""


from pprint import pprint
pprint(jsonObj)

"""
Explanation: pprint or "pretty print" allows us to display JSON objects in a readable format. Let's make a pretty print of our JSON repsonse.
End of explanation
"""


dataDict = jsonObj[0]
print dataDict.keys()

"""
Explanation: Our response contains only one item in the JSON list. We'll extract to a dictionary and print it's items.
End of explanation
"""


lat = float(dataDict['lat'])
lng = float(dataDict['lon'])
print "The lat,lng

d = jsonObj[0]
d['lon'],d['lat']

"""
Explanation: Now we can easily grab the lat and lon objects from our response
End of explanation
"""


print "The address {0} is located at\n{1}° Lat, {2}° Lon".format(address,lat,lng)

"""
Explanation: Now let's inform the user of the result of the whole process...
End of explanation
"""


