location — Geo-Location Services on iOS

The location module allows you to access geo-location data (e.g. GPS) on iOS. Additionally, you can use the location module to convert addresses to coordinates and vice-versa (geocoding and reverse-geocoding).

Note

The first time this module is used, a system-provided permission alert will be shown. Until you have given the app permission to access your location, most functions won’t return meaningful results.

Functions in the location module:

location.get_location()

Return the most recently obtained location data. The return value is a dictionary containing various numbers that describe the current location (most importantly, ‘longitude’, ‘latitude’ and ‘timestamp’). This dictionary can be used as a parameter for the reverse_geocode() function. If no location data has been obtained yet (or you haven’t authorized the app), the return value may be None.

location.start_updates()

Start updating location data. This should be called before using get_location(). To save energy, it is recommended to call stop_updates() when you no longer need location data.

location.stop_updates()

Stop updating location data.

location.geocode(address)

Try to convert an address dictionary to geo-coordinates. The return value is a list of possible coordinates (can be empty if no results are found). Each entry in the list is a dictionary with ‘longitude’ and ‘latitude’ keys.

Example:

import location
address_dict = {'Street': 'Infinite Loop', 'City': 'Cupertino', 'Country': 'USA'}
results = location.geocode(address_dict)
print results

location.render_map_snapshot(lat, lng, width=1000, height=1000, map_type='standard', show_poi=True, img_width=240, img_height=240, img_scale=0)

Render/download a snapshot image of the given map region (using the Apple Maps framework).

The lat and lng parameters determine the latitude and longitude of the map’s center. width and height (in meters) indirectly set the map’s scale factor. map_type can be 'standard', 'satellite' or 'hybrid'.

The return value is a ui.Image with the given size (img_width/img_height) and scale (0 by default, i.e. the current device’s screen scale).

Example:

import location
img = location.render_map_snapshot(48.8582, 2.2945, map_type='satellite', img_width=512, img_height=512)
img.show()

location.reverse_geocode(location)

Try to convert a location (longitude/latitude) to a human-readable address. The location parameter should be a dictionary containing values for ‘longitude’ and ‘latitude’. The return value is a list of possible address dictionaries (usually just one).

Example:

import location
coordinates = {'latitude': 37.331684, 'longitude': -122.030758}
results = location.reverse_geocode(coordinates)
print results

location.is_authorized()

Returns True if access to location data is currently allowed, False otherwise (e.g. if the permission dialog hasn’t been shown yet or if access is denied due to parental controls).