Developer Console

Frequently Asked Questions (v2.5)

The following sections list commonly asked questions about the Amazon Maps API.

Getting Started

Q: What is the Amazon Maps API?
The Amazon Maps API 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.5.
Q: What do I need to get started with the Amazon Maps API?
Download the Maps API from the SDK Downloads page. The zip file includes the Amazon Maps API, reference documentation, and example code.
Q: On which devices is the Amazon Maps API supported?
The Amazon Maps API v2.5 is compatible with Fire OS 5 and higher, which is available on Fire tablets (7th generation and above). 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?
No, Kindle Fire does not support the Amazon Maps API.
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 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 Getting Started with the Amazon Maps API (v2.5), specifically steps 7 through 9.

Developing with the Amazon Maps API

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.
Q: How do I get the user's current location?
The user must enable location services on their Fire tablet. 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. To retrieve the user's current location, use the android.location APIs. For apps targeting Fire OS 7+ devices, you must check if permissions are granted by the user. If required location permissions are not there, app should request the user to grant the permissions as documented here.
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.5 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.5).
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.5).
Q: Can I use the Amazon Maps API inside an Android fragment?
The Amazon Maps API v2.5 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.5).
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.5 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 Getting Started with the Amazon Maps API v2.5 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.5 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 the steps in Getting Started with the Amazon Maps API.
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 Getting Started with the Amazon Maps API. 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.
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.5).
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.
Q: I can't see traffic information on my map.
The Amazon Maps API v2.5 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.5, all street view methods return null or throw an UnsupportedOperationException.

Last updated: Nov 12, 2020