Home > Services & APIs > Build > Maps

Amazon Maps API Frequently Asked Questions

Getting Started

Q: What is the Amazon Maps API?

A: The Amazon Maps API is a programming interface that enables you to add mapping capabilities to your app on Fire phone and most Fire tablets.

The most recent version of the Amazon Maps API is version 2.

The previous version of the Amazon Maps API is version 1. This version is still available.

Q: What do I need to get started with the Amazon Maps API?

A: Download the Amazon Apps & Games Services SDK.

For details about getting started with v2, see Getting Started with the Amazon Maps API v2.

For information about using v1, see the documentation at Amazon Maps API v1.

Q: On which devices is the Amazon Maps API supported?

A: The Amazon Maps API v2 is compatible with Fire OS 4.5.1 and higher, which is available on 3rd and 4th generation Fire tablets, and Fire phone.

The Amazon Maps API v1 is compatible with the Fire phone and all Fire tablets except Kindle Fire (1st Generation).

Amazon Fire TV does not include location services and does not support the Maps API.

Q: Is the Amazon Maps API available on Kindle Fire (1st Generation)?

A: No, Kindle Fire (1st Generation) does not support the Amazon Maps API.

Q: Is Amazon Maps API available on Kindle Fire (2nd Generation)?

A: The Amazon Maps API v2 is not available on the 2nd generation or earlier Kindle Fire. However, the previous version of the Maps API is available on these tablets.

Q: What are the terms of use for the Amazon Maps API?

A: The Amazon Maps API is covered by the Amazon App Distribution and Services Agreement, the Amazon Program Materials License Agreement, and the HERE Materials Terms and Conditions.

Q: Are there usage quotas or limits on the Amazon Maps API?

A: At this time, there are no specific usage quotas or limits for the Maps API. However, we reserve the right to throttle or shut down your application in the event we reasonably believe your use of the Maps API exceeds typical or expected usage or creates material technical burdens on our (or our partner’s) systems.

Q: Where do I get an Amazon Maps API key?

A: Amazon Maps does not use an API key as Google Maps does. To get map tiles and other Amazon-provided data you must register your app with the Amazon Apps & Games Developer Portal. Maps registration is an additional process to submitting your app for testing and publication. You must register the debug and release versions of your app separately.

For details about registering and testing with v2, see Registering and Testing Your Amazon Maps API v2 App.

For details about registering and testing with v1, see Building and Testing your Maps App.

Q: What are the differences between the Amazon Maps API and the Google Maps API?

A: The Amazon Maps API v2 offers interface parity with the Google Maps API v2. Most classes and method calls in your Google Maps–compatible app work the same on Amazon devices.

However, there are some features that are not supported. In these cases, the Amazon Maps API includes stub methods, but they do not function. For details, see Differences between the Amazon Maps API v2 and Google Maps API v2.

The Amazon Maps API v1 offers interface parity with the Google Maps API v1. However, some elements in the API do not function identically. For details, see Migrating an App from Google Maps.

Developing with the Amazon Maps API

Q: How do I convert my Google Maps app to use the Amazon Maps API?

A: You can migrate your app from the Google Maps API in just a few steps.

To migrate a Google Maps API v2 app, see Migrating an App from Google Maps v2.

To migrate a Google Maps API v1 app, see Migrating an App from Google Maps v1.

Q: How do I create an app that will run even if the Amazon Maps API is not available on the device?

A: Develop your application to gracefully degrade when the Maps API is unavailable. You can create a single APK for all Fire tablets, including tablets without the Maps library runtime.

For the Amazon Maps API v2, you can use the AmazonMapsRuntimeUtil.isAmazonMapsRuntimeAvailable() method to check for the availability of Amazon Maps. See the "Verifying that Amazon Maps is Available on the Device" section in Configuring Your Project to Use the Amazon Maps API v2.

For the Amazon Maps API v1, you can check for the existence of the MapView class. See "Modifying Your App to Degrade Gracefully" in Migrating an App from Google Maps v1 for details.

Q: One of the MapView constructors requires an API key. I thought you said you didn't use an API key.

A: The API key parameter to the MapView constructor (MapView(context, apiKey)) is ignored. This constructor is included to provide interface parity with the Google Maps API v1.

Note that this only applies to the Amazon Maps API v1. The MapView constructor in v2 does not include a parameter for an API key.

Q: How do I get the user's current location?

A: For both versions of the API, the user must enable location services on the Fire tablet or Fire phone.

For the Amazon Maps API v2, you can use AmazonMap.setMyLocationEnabled() to turn on the My Location layer. When enabled, the user's location is displayed as a blue dot on the screen. The map can also display a Locate Me button that moves the map camera to the user's location. See "Showing the User's Location and 'Locate Me' Button" in Displaying an Interactive Map with the Amazon Maps API v2

To retrieve the user's current location, use the standard android.location APIs.

For the Amazon Maps API v1, you can use the MyLocationOverlay class to find the user's current location and add a marker to the map. As the user moves, the location marker is automatically updated.

See Understanding the Amazon Maps API v1 for details.

Q: How can I convert from an address to a location (latitude/longitude) or vice versa?

A: Both versions of the Amazon Maps API support the core android.location classes. These classes include Geocoder, which can be used for translating between addresses and latitude/longitude locations.

Q: How do I add markers to the map?

A: For the Amazon Maps API v2, you can add Marker objects to your map. You can also draw lines and shapes on the map. See Drawing Markers and Objects on the Map with the Amazon Maps API v2.

For the Amazon Maps API v1, use the ItemizedOverlay class. An ItemizedOverlay contains OverlayItem objects, which are used to indicate points of interest on the map. See Understanding the Amazon Maps API v1.

Q: How can I change the part of the world shown on the map in code?

A: For the Amazon Maps API v2, obtain a CameraUpdate representing the new map camera properties (latitude/longitude, zoom, bearing, and/or tilt) and pass it to one of the AmazonMap.moveCamera() or AmazonMap.animateCamera() methods. See "Moving and Zooming the Camera" in Displaying an Interactive Map with the Amazon Maps API v2.

For the Amazon Maps API v1, use the MapController class to move the map center. See "Controlling the Map's Center and Zoom Level" in Understanding the Amazon Maps API v1.

Q: Can I use the Amazon Maps API inside an Android fragment?

A: The Amazon Maps API v2 supports the use of fragments. You can add a MapFragment to the XML layout for your app, or you can define the fragment in code. See "Displaying the Map in a MapFragment" in Displaying an Interactive Map with the Amazon Maps API v2.

The Amazon Maps API v1 does not support fragments.

Q: When the user clicks a marker, I want to display a window with clickable options, such as a phone number the user can click to dial. The default info window does not allow this. How can I accomplish this?

A: The View displayed by the marker info window is rendered as an image. This means that it cannot receive events such as clicks. Some options for working around this include:

  • Implement a custom popup with the clickable links and set it to appear when the user clicks on the standard info window. The user can then click the marker to see the standard window, and then click the window to see the additional popup. Implement the OnInfoWindowClickListener callback interface to call your custom popup.

    The CapitolHillCoffee sample app illustrates this option. See Using the Amazon Maps API v2 Sample App.

  • Implement a custom popup with the clickable links and set it to appear when the user clicks on a marker, replacing the default info window completely. Implement the OnMarkerClickListener callback interface to call this popup instead of the normal info window.<

Note that this only applies to the Amazon Maps API v2. The v1 API does not include default info windows for markers.

Q: How do I configure ProGuard exceptions when working with the Amazon Maps API?

A: If you are using ProGuard to obfuscate your code, you need to update your proguard-project.txt with rules for the Amazon Maps API.

For Amazon Maps API v2, add the following lines to proguard-project.txt:

# Remove this line if you are using SupportMapFragment
-dontwarn com.amazon.geo.mapsv2.SupportMapFragment

# Keep all Maps internal interfaces
-keep public class com.amazon.geo.mapsv2.**internal.* {
    *;
}

# Keep all Parcelable Creators
-keepnames class * implements android.os.Parcelable {
    public static final ** CREATOR;
}

# Keep all resource identifiers
-keepclassmembers class **.R$* {
    public static <fields>;
}

For Amazon Maps API v1, add these lines to proguard-project.txt:

-ignorewarnings
-dontwarn com.amazon.geo.maps.**
-keep class com.amazon.geo.maps.** {*;}
-keepattributes *Annotation*
-libraryjars path/to/amazon_maps_api.jar

Q: How can I test my maps app?

A: For the Amazon Maps API v2, see Registering and Testing Your Amazon Maps API v2 App.

For the Amazon Maps API v1, see Building and Testing your Maps App.

Are there any samples showing how to work with the Amazon Maps API?

Yes. The CapitolHillCoffee sample app is available for both v1 and v2. This sample illustrates several common tasks in the API. The samples are also useful for reviewing the differences between a v1 app and a v2 app, as the basic functionality is the same in both versions.

For details, see Using the Amazon Maps API v2 Sample App.

Submitting Your App to the Amazon Apps & Games Developer Portal

Q: How do I submit my maps app to the Amazon Apps & Games Developer Portal?

A: If you have already created a debug registration for your app, you can use the portal to submit your app as you would with any other app. If you have not yet registered your app, see one of the following topics for details:

Q: Where can I get help with my maps app?

A: For additional support with your maps app, please Contact Us.

Troubleshooting

Q: Why are map tiles not showing up in my app? All I see are gray squares.

A: Map tiles are not available if you have not used the Amazon Apps & Games Developer Portal to register your app. Registration for Amazon Maps is different from submitting your app to the portal for testing and publication. For details, see:

The Fire tablet or Fire phone must also be registered to an Amazon account for map tiles to appear. Check this on the device in the My Account section of the device settings.

Finally, your app cannot access map tiles if you have not defined the android.permission.INTERNET permission in AndroidManifest.xml. For details, see:

Q: When the user clicks a marker in my app, the info window that appears cuts off long title or snippet text. How can I make the text in the window wrap?

The default info window does not wrap the title or snippet text. You can provide your own formatting for info windows by setting a custom info window adapter. Implement the AmazonMap.InfoWindowAdapter interface and pass it to AmazonMap.setInfoWindowAdapter(). For an example, see Drawing Markers and Objects on the Map with the Amazon Maps API v2.

Note that this only applies to the Amazon Maps API v2. The v1 API did not include default info windows for markers.

Q: My maps app builds successfully, but crashes when I try to run it. In the stack trace, I see the error message java.lang.RuntimeException: Stub!.

A: This issue only applies to the Amazon Maps API v1. The amazonmaps-1.0.2.jar file contains stub implementations of the Amazon Maps API. It does not contain actual implementations of the Maps API classes. When you bundle amazonmaps-1.0.2.jar with your project, the stub classes throw a runtime exception when invoked. You can verify the cause of the error by running the Android SDK dexdump tool on your classes.dex. If you see Class descriptor: 'Lcom/amazon/geo/maps/MapActivity;' in the output, your app includes the stub classes.

To avoid this problem, make sure that you link amazonmaps-1.0.2.jar as an external library. If you are using Eclipse, make sure to click Add External JARs when you add the amazonmaps-1.0.2.jar file. Do not simply add the file as a JAR.

Never add the amazonmaps-1.0.2.jar to the libs directory for your project, because this will also bundle the stub classes into your app.

See Building and Testing Your Maps App for details about configuring your project.

Q: My app crashes immediately with an IllegalStateException error.

A: In the Amazon Maps API v2, this is probably because your AndroidManifest.xml is missing required meta-data tags.

You can set these automatically by enabling manifest merging. This automatically combines settings in library manifests with your project's manifest.

For details, see the "Updating the AndroidManifest.xml" section in Configuring Your Project to Use the Amazon Maps API v2.

Q: I can't see traffic information on my map.

A: The Amazon Maps API v2 supports the traffic layer. Be sure you've turned it on with the AmazonMap.setTrafficEnabled() method.

The Amazon Maps API v1 does not support traffic. The MapView.setTraffic() and MapView.isTraffic() methods behave as expected, but no traffic information appears on the map.

Q: I can't see street view information on my map.

A: At this time the Amazon Maps API does not support street view.

In the Amazon Maps API v2, all street view methods return null or throw an UnsupportedOperationException.

In the Amazon Maps API v1, the MapView.setStreetView() and MapView.isStreetView() methods behave as expected, but no street view information appears on the map.

International Maps Support

Q: In which countries is the Amazon Maps API supported?

A: The Amazon Maps API v2 is supported in countries where Fire tablets are sold, except for China, Japan, and India.

The Amazon Maps API v1 is supported in countries where Fire tablets are sold, except for China and Japan.

Q: Which countries have limited maps and geocoding services?

A: The Amazon Maps API allows you to display map tiles on a global basis, and most countries where Fire tablets are sold have detailed maps and geocoding services. To see the list of countries where the tablets are sold, open the Amazon.com product page for Kindle Fire HD 7" and click the Selected Country drop-down menu. Within the countries where the tablets are sold, the following countries and regions have limited map detail, geocoding services, and positioning data:

American Samoa
Armenia
Barbuda
Benin
Bhutan
Cameroon
Cape Verde
Central African Republic
Congo
Congo, Democratic Republic
Cook Islands
Côte d'Ivoire
Cyprus
Dominica
Equatorial Guinea
Ethiopia
Faroe Islands
Fiji
French Polynesia
Gabon
Georgia
Greenland
Grenada
Guam
Guinea-Bissau
Haiti
Japan
Kiribati
Lao People's Democratic Republic
Liberia
Madagascar
Mariana Islands
Marshall Islands
Martinique
Mauritius
Mayotte
Micronesia
Montserrat
Myanmar
Nauru
Netherlands Antilles
New Caledonia
Niue
Norfolk Island
Palau
Saint Kitts and Nevis
Saint Lucia
Saint Vincent and the Grenadines
Samoa
Sao Tome and Principe
Seychelles
Solomon Islands
Timor-Leste
Togo
Tonga
Turks & Caicos
Tuvalu
Vanuatu
Wallis and Futuna
Zambia

The following countries and regions have detailed maps and geocoding services, but limited positioning data:
Cayman Islands
Dominican Republic
French Guiana
Honduras
Philippines
Reunion Island
Saint Barthelemy