Amazon Maps API Frequently Asked Questions

Getting Started

Q: What is the Amazon Maps API?
The Amazon Maps API is a programming interface that enables you to add mapping capabilities to your app on most Fire tablets. The most recent version of the Amazon Maps API is version 2.
Q: What do I need to get started with the Amazon Maps API?

Download the Amazon Apps & Games Services SDK. For details about getting started with the API, see Getting Started with the Amazon Maps API v2.

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

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. 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)?

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

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

The Amazon Maps API v2 is not available on the 2nd generation or earlier Kindle Fire.

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

The Amazon Maps API is covered by the Amazon Developer Services Agreement, the Amazon Program Materials License Agreement, and the HERE Location Platform Services Online Terms and Conditions.

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

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?

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 of the API, see Registering and Testing Your Amazon Maps API v2 App.

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

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, some features 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.

Developing with the Amazon Maps API

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

You can migrate your app from the Google Maps API in just a few steps. See Migrating an App from Google Maps v2 for details.

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

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. 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.

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

The user must enable location services on the Fire tablet or Fire phone. 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.

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

The Amazon Maps API supports 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?

The Amazon Maps API v2 supports adding 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.

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

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.

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

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.

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?

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.<

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

If you are using ProGuard to obfuscate your code, you need to update your proguard-project.txt with rules for the Amazon Maps API. 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>;
}
Q: How can I test my maps app?

See Registering and Testing Your Amazon Maps API v2 App.

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

Yes. The CapitolHillCoffee sample app is available. This sample illustrates several common tasks in the API. 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?

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 Registering and Testing Your Amazon Maps API v2 App.

Q: Where can I get help with my maps app?
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.

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 Registering and Testing Your Amazon Maps API v2 App. The Fire tablet 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 Configuring Your Project to Use the Amazon Maps API v2.

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.

Q: My app crashes immediately with an IllegalStateException error.

This is probably because your AndroidManifest.xml is missing required metadata 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.

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

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

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.

International Maps Support

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

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

Q: Which countries or regions have limited maps and geocoding services?

The Amazon Maps API allows you to display map tiles on a global basis, and most countries or regions where Fire tablets are sold have detailed maps and geocoding services. To see the list of countries or regions 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 or regions 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