Location and Maps

he MapView feature lets the developer integrate one or more Google Map views into their app, and supports various methods of two-way communication between the map contents and the surrounding application, including address or landmark lookup, marking the map with pins, and reverse geocoding (converting latitude/longitude into the closest street address).

Note

MapView is currently iOS-only, and therefore will not run in the Corona Simulator. Build for iOS devices or for the XCode Simulator to use this feature. For an example of many of these APIs, see the new "MapView" sample project distributed with the SDK.

(1) Constructor

myMap = native.newMapView( left, top, width, height )
Renders a MapView within the specified boundaries and returns a Corona display object. This object can be moved or rotated like any other display object.

Note that this API also allows you to do things with maps that Apple may not accept under its interface guidelines, including moving maps around the screen, adding many independent maps to the same screen, and turning map rectangles into physics objects.

(2) Map attributes

myMap.mapType = "standard"
myMap.mapType = "satellite"
myMap.mapType = "hybrid"
A readable/writeable string attribute for the type of map display. Possible values are "standard", "satellite" and "hybrid". The default is "standard".

myMap.isZoomEnabled = true
A Boolean that determines whether users may use pinch/zoom gestures to zoom the map. Default is true.

myMap.isScrollEnabled = true
A Boolean that determines whether users may scroll around the map. Default is true.

myMap.isLocationUpdating = true
A Boolean indicating whether the map should display the user's current location. When this value is true, the map will update continuously as the user moves. The initial default is false.

isVisible = myMap.isLocationVisible
A (read-only) Boolean value indicating whether the user's current location is visible within the area currently displayed on the map. This is based on an approximation, so it may be the case that the value is true when the user's position is slightly offscreen.

(3) Map functions

latitude, longitude = myMap:getAddressLocation( "gough and post, sf" )
latitude, longitude = myMap:getAddressLocation( "120 university, palo alto, ca" )
latitude, longitude = myMap:getAddressLocation( "eiffel tower" )
Returns the numerical latitude and longitude values of the given location string, obtained using a Google maps HTTP method. These values can then be used to place a marker on the map, recenter the map to the desired location, or perform any of the other functions that use a (latitude, longitude) pair.

This function will accept virtually any address or intersection format as input (along with the names of some famous landmarks), since it submits the string directly to Google's address parser, which is fairly flexible.

myLocation = myMap:getUserLocation
Returns a table containing values for the user's current location. The fields of the table are the same as those currently used in Corona GPS location events, and are as follows:

myLocation.longitude
myLocation.latitude
myLocation.altitude
myLocation.accuracy
myLocation.time
myLocation.speed
myLocation.direction
myLocation.isUpdating -- a Boolean that flags whether the location is currently updating

Note: the difference between the above and the normal Corona "location" events is that this is a pollable function, while the "location" events are periodically pushed by the device's GPS hardware. In other words, since an onscreen map object already exposes a location property, you don't need to additionally activate the normal Corona location listener to obtain the current user location.

If you build for the XCode Simulator, the user location returned will not be your actual location, but instead will default to the address of Apple headquarters (1 Infinite Loop, Cupertino, California).

myMap:setRegion( latitude, longitude, latitudeSpan, longitudeSpan, isAnimated )
Moves the displayed map region to a new location, with the new center point and horizontal/vertical span distances given in degrees of latitude and longitude (which implicitly set the zoom level). iOS will sanity-check the span settings, and will interpolate a consistent zoom level even if the latitudeSpan and longitudeSpan are specified with radically different values. The final parameter is an optional Boolean (default false) that determines whether the transition is animated or happens instantly.

Note that degrees of latitude and longitude cover large distances on the Earth, so fairly small changes to extended decimal values will translate into big position changes in the map, especially at close zoom levels. Also note that most of the planet's map locations are fairly empty, so it will generally be easier to work with known latitude/longitude values when experimenting with maps. Try looking up your own address on a public geocoding site like http://geocoder.us (US addresses only) if you need a quick test location.

myMap:setCenter( latitude, longitude, isAnimated )
Moves the displayed map region to a new location, using the new center point but keeping the zoom level the same. The final parameter is an optional Boolean (default false) that determines whether the transition is animated or happens instantly.

myMap:addMarker( latitude, longitude, { title="Displayed Title", subtitle="subtitle text" } )
Adds a pin to the map at the specified location. The specified title and subtitle will appear on a small popup when the pin is touched.

myMap:addMarker( latitude, longitude )
(coming soon)
Adds a pin to the map at the specified location, with no popup when the pin is touched.

myMap:removeAllMarkers()
Clears all pins from the map.

(4) Address Lookup from Position (Reverse Geocoding)

A latitude/longitude pair (either the user's current location, or any arbitrary set of coordinates) can be converted to an approximate address value. This requires a round trip through Google's reverse-geocoding servers, so there may be some latency, and the data quality may vary depending on the state of Google's address mapping around the world.

To obtain this data, you first need to activate the "mapAddress" event listener. With that listener active, any location submitted to the nearestAddress() function will be returned asynchronously as a "mapAddress" event that includes parameters for the various possible address details. This listener can either be a global (Runtime) listener or a table listener on the map object itself -- the latter method might be useful if you have multiple maps on the same screen.

local function mapAddressHandler( event )
-- handle mapAddress event here
print( "The specified location is in: " .. event.city .. ", " .. event.country )
end

myMap:nearestAddress( latitude, longitude )

Runtime:addEventListener( "mapAddress", mapAddressHandler )
The event object returned to the specified handler function has the following attributes:

event.street -- the street name
event.streetDetail -- the street number (or other specifier for location on the street)
event.city -- the city or town
event.cityDetail -- additional city information, such as neighborhood
event.region -- the state, province, or similar region within the country
event.regionDetail -- the region below the state level (e.g., the county, in the U.S.)
event.postalCode -- the postal code
event.country -- the country name
event.countryCode -- the standard country abbreviation
There is also an error field:

event.isError
This is a Boolean that indicates whether the reverse-geocoding server returned an error rather than a location. Normally this will be false, but in the error case it will be true (and the other event attributes will be empty).