MapBox Help
Have you found yourself a bit lost in the mapmaking process? We've made it easy to find the answer you're looking for so you can get back on the road right away.
Table of contents
Questions and answers are sorted by product or feature into the following categories.
Not finding what you're looking for? Ask on our support forums
Are you a developer? Check out our full documentation
Basic MapBox questions
How do I set my map's privacy?
Map privacy allows you to show/hide a map from your public account page and API listing requests. Private maps are still accesible if you know the URL.
How can I report a problem with a map?
Use the map feedback form to let us know.
Our maps rely on data from OpenStreetMap, a global volunteer project that everyone can contribute to. If you see anything else off in areas you are familiar with, we encourage you to go to openstreetmap.org, create an account, and make make the changes directly. If you're new to OpenStreetMap, you can learn how to edit by clicking the dropdown arrow next to the Edit tab and select "Edit with iD". You'll have the option to go through an interactive tutorial to get you started.
How frequently is MapBox Streets updated?
MapBox Streets is re-rendered with up to date OpenStreetMap data roughly once every five minutes.
How do I enable the terrain visualization?
Click the mountain button next to the Areas layer to enable a terrain visualization featuring hillshading and elevation contour lines.
How do I enable satellite imagery?
Enable the Satellite layer to add aerial imagery to your map. Read the announcement blog post for information about coverage.
How do I enable Retina mode?
Click the 2x button next to the Streets layer to increase text and feature size by two times, which will make the map suitable for Retina displays.
This change will apply to the entire map. If you need a retina version and a non-retina version create another map and switch between them based on device resolution. Learn more about using the Retina option on iOS in the MapBox iOS SDK Guide.
What is the difference between embeds and API?
Embeds are a quick way to get your MapBox maps onto webpages. The MapBox JavaScript API gives you full control over the styling, workflow, and many other aspects of your map. Before diving into specifics it can be helpful to see concrete examples of embeds and custom API usage.
| Embeds | API |
|---|---|
| Poisoned Places: Air Pollution In Your Town NPR News | Opportunity Index Opportunity Nation |
| Connect America Fund: Putting Consumers on the Map The FCC | PRCC Disaster Data Pacific Rim Coordination Center |
| Durban: World Bank Publishes High Resolution Climate Predictions Development Seed | U.S. Census Map NPR News |
| A New Running Map Tom MacWright | Where people get towed in Boston The Boston Globe |
| Rooftop Solar Challenge to Cut Solar's Red Tape Department of Energy | Horn of Africa Crisis Interactive Map ONE |
Embeds vs. API: What's possible?
Here's a rough breakdown between the capabilities of embeds and APIs:
| Feature | Embeds | API |
|---|---|---|
| Compositing | Yes | Yes |
| Interaction | Yes | Yes + custom CSS |
| Legends | Yes | Yes + custom CSS |
| MapBox Streets | Yes | Yes |
| Share links | Yes | Yes |
| Animation with Easey | No | Yes |
| Dynamic layer switcher | No | Yes |
| Custom tooltips | No | Yes |
| Integration with external APIs | No | Yes |
Embeds vs. API: Which should I use?
Embeds work well for
- Blog posts & press releases. When putting a map in a post or article embeds give you a quick, easy way to integrate an interactive map.
- Maps that tell the whole story. If your map can stand alone embeds give you a simple, direct wrapper around your content.
- Prototyping. If you're making a more sophisticated website or application embeds are often a great way to start adding and integrating maps.
However, once you get going you may find embeds limiting for certain use cases. It may make sense to start using the MapBox JavaScript API directly for
- Custom styling. You need tooltips, legends, or controls that all match your website or application's look and feel.
- Animation, layer switchers, and more. You need to integrate Easey or some other advanced map manipulations to tell your story effectively.
How do I embed a map on WordPress?
To embed your map in WordPress you may want to install the MapBox WordPress plugin. The plugin converts MapBox embed codes into a WordPress shortcode, making it easy to edit embeds once they've been added to your site.
How do I embed a map on Drupal?
Drupal sites usually implement content filters that restrict the HTML tags that are allowed on pages. When embedding a MapBox map on a Drupal site look for an input format called Full HTML or Extended HTML that allows iframe tags to be used. If you have trouble pasting your embed into a Drupal site, ask a site administrator to set up an input format that allows iframe tags.
How do I embed a map on a webpage?
MapBox embeds are the easiest way to share maps on any website - you can copy & paste code that adds a full, dynamic map to any page. From your map’s page click the edit button, then click Embed. Click the text box labeled HTML embed code and copy the text, then paste the code into your website.
Are you a developer? Use the MapBox JavaScript API for complete control.
Can I download the source styles for MapBox Streets?
The stylesheets for MapBox Streets are not available. You may be interested in taking a look at OSM Bright, an open-source streetmap template from MapBox.
How do I delete a map?
You can permanently delete a map from your account page. Find the map you want to delete and click the delete button.
How do I customize my map's colors?
MapBox allows you to customize the colors of your map to fit the look and feel of your app or brand.
Click the edit button to expand the map's edit drawer and select the Layers tab. To change the map colors you can select from the list of availabile presets or use the sun button to reveal color sliders for each layer. Each layer has three sliders:
- Hue: adjust the portion of the color spectrum displayed for each layer.
- Saturation: adjust the color saturation.
- Lightness: adjust the value range.
Click Save to make your changes permanent.
How do I create a new map?
Click the New map button on your account page to create a new map. You can customize this map, add layers and markers, and embed it into your website or application.
How do I change the map's label language?
By default your map will use labels in the native language of each area. Click the en button next to the Streets layer to use English-language labels where available.
What are the attribution requirements for my map?
You are required to provide attribution to OpenStreetMap and its contributors when using one or more of the Streets, Buildings, Areas, Water, and Land layers on a map.
There are a few different ways to display attribution based on publishing method:
- Embeds: Attribution is displayed automatically.
- mapbox.js: If you use
mapbox.auto(), attribution is displayed automatically. Otherwise, you must manually add the attribution control. - MapBox iOS SDK: See the guide for more information.
- Linking to our attribution page on an about page or info panel.
- For any other methods you are responsible for ensuring the appropriate display of the attribution.
How do I add markers to my map?
- Open or create a map.
- Click the Markers tab of your new map.
- Give your first marker a title and description. The description may contain basic HTML.
- Click Place on map, and then click again on the map at the location you want to add the marker.
- Click on the pen to choose the marker's size, color and symbol.
- Add additional markers by clicking the Add marker button.
How do I add custom layers?
- Click the Add layer button under the Layers tab of your map.
- Choose the custom layer to add from the thumbnails displayed. If you have not designed and uploaded any custom layers yet, see the Designing section above to upload your first custom layer.
- You can remove any custom layers by clicking the X and reorder custom layers by dragging them in the layers list. Click Save when you're done to make any changes permanent.
Payment Plans
How can I upgrade or downgrade my plan?
- Login and navigate to the change plan page.
- Find the plan you need and select Upgrade or Downgrade. Some plans may be disabled if your current usage is greater than the plan allows.
How do I update my payment information?
- Login and navigate to the billing page.
- Under Payment information click Update and provide new payment card information securely.
Can I get statements, invoices, or receipts?
We send you a receipt via email each time we charge you and you can access complete statements for your account.
Can you show my organization name, address or VAT number on my statements?
You can provide optional contact information to display on your statements.
- Login and navigate to the billing page.
- Click the Optional Contact Info button.
- Enter the relevant information in the text field and click Update Information.
- Your statements will now show the new information.
How can I pay for MapBox?
You can pay for your MapBox account using a Visa, Mastercard, American Express or Discover card. If you do not have access to one of these cards consider using a prepaid card instead. Prepaid cards are available from several vendors, including:
On a case-by-case basis, we offer invoicing for annual Plus and Premium subscriptions. Contact support for details.
Can I pay annually?
Yes. Login to your MapBox account or signup for a free account if you don't have one. Head over to the Change plan page, choose Yearly billing and select the annual plan you need.
Do you have a special plan for students and non-profits?
We don't have a specific plan for students, but you can sign up for a free account at no charge. If you represent a non-profit, contact support to dicuss options.
How many map views does the free plan offer?
The free account offers 3,000 views per month and 50 MB storage.
How do I delete my account?
Are you sure you want to completely delete your account? If you're not using your plan you may just want to cancel your subscription and keep your account for free with 3,000 map views per month and 50 MB of storage.
If you really want to delete your account, follow these steps.
- Login to your account and delete each of the maps you no longer wish to use.
- Navigate to the change plan page.
- Click Delete account.
Do you offer custom plans?
MapBox can help you with custom mapping work and help implement bleeding edge mapping technologies. Contact us and we'll be happy to discuss your situation and what we can offer.
How do I change my account usage?
- Login and navigate to the billing page.
- Your account page shows you your current MapBox Hosting plan and your account's storage and transfer usage.
How do I cancel my plan?
Sorry to see you go! To cancel your account:
- Login and navigate to the change plan page.
- Click Cancel.
My Account
How do I reset my password?
If you're having trouble logging in try resetting your password by providing the email address that's associated with your MapBox account. We'll send you an email with further instructions.
If you don't remember your email address or you're having other access problems contact support and we'll look into it.
What is a map view?
Web maps consist of many individual image tiles and as users interact with maps by panning or zooming more tiles are loaded. We measure a single map view as 15 map tiles which is typical for a single page view on most websites. Multiple map views can be generated during a single session as your users explore and interact with the map.
Each request against our Static API counts as one map view.
How do I view my maps' statistics?
Click the Stats link on your account page to see account level statistics or click the statistics button on a map page to see map level statistics.
What do I do if the login link in email doesn't work?
The login link expires after 24 hours or after it's clicked once. You can request another link with the password reset form.
What happens if I exceed my plan?
If you have a paid account, additional map views are automatically served at $0.50 per 1,000 map views making it easy and affordable to handle temporary spikes in traffic. And we'll notify you so you can switch plans if necessary.
If you have a free account, you can upgrade your plan to keep your maps online.
How do I complete my profile?
- Login and navigate to the account settings page.
- Fill out the Name, Website and Description fields then click Update profile. These fields are shown on your MapBox account page and can help other users get to your website if they are interested in your work.
How do I change my username?
It is not possible to change your username as doing so would break API URLs, which could cause unanticipated problems. Instead you may signup for a new account, copy over your maps, and update your web and mobile applications to reference the new account and maps. Once this transition is complete, you can optionally cancel the old account.
How do I change my password?
- Login and navigate to the password settings page.
- Click the Account link on your user toolbar to view your Account settings.
- Enter your new password and confirm it, then click Change password.
How do I change my email address?
- Login and navigate to the account settings page.
- Click the Account link on your user toolbar to view your Account settings.
- Enter your new email address and click Update email.
TileMill Design Studio
How do I use a custom map image with TileMill?
If your data is completely non-georeferenced (has no latitude, longitude position), and it's raster, you might want to check out this guide. The trick with TileMill is to make any non-georeferenced data follow the basic coordinates of the mercator projection in order to eliminate distortion.
How do I optimize map usage?
There are some quick and easy ways to make sure you are getting the most storage and transfer possible out of your MapBox account.
By default TileMill uses the png (24-bit) as its image format when uploading or exporting a map. While this format provides very high image quality many maps can make use of the more efficient png (8-bit) or jpeg formats with little noticeable effect. Changing your map to use one of these formats can greatly reduce your storage and transfer usage.
To adjust the format of a map, open its project in TileMill and click the Project settings icon on the top right.
Then choose from the Format dropdown your desired format and Save. Upload or export your map again to make use of your changes in your MapBox account.
Can I build indoor floorplans with TileMill?
If your data is completely non-georeferenced (has no latitude, longitude position), and it's raster, you might want to check out this guide. The trick with TileMill is to make any non-georeferenced data follow the basic coordinates of the mercator projection in order to eliminate distortion.
If you want your data to integrate with the world (zoom out from your building, see the world, etc), you'll need to georeference your data, but that's likely unnecessary.
How do I design and upload custom layers from TileMill?
Use TileMill, an open-source map design studio to make custom layers from your data. See the TileMill introduction for more information.
Click the Settings icon in the left panel and Authorize TileMill to upload directly to your MapBox account. You may be asked to login to MapBox.
Click the Upload option in the TileMill exports panel. You will see a popup with a preview of your layer so you can check it one last time. Once you're ready click the Upload button.
Once your layer is uploaded click View to preview the map on MapBox.
After your layer is validated it will ready for use as a layer in other maps.
If your MBTiles does not pass validation contact support with the complete error message.
JavaScript API
What is the JavaScript API?
Developers can use mapbox.js for custom integration of maps into their site. Take a look at the examples and API.
Can I use MapBox with a different API?
Developers can also use a wide range of open-source APIs like Leaflet, OpenLayers, osmdroid, polymaps, and more by using the REST API's tile endpoint.
The MapBox iOS SDK
Do you provide an iOS SDK?
The MapBox iOS SDK provides a complete toolset for building native iOS mapping applications and works similarly to Apple's MapKit. Take a look at the guide, full API reference, and example code snippets.
How can I make offline maps for mobile devices?
The MapBox iOS SDK has full support for offline maps using any or all of three methods. With cache-based methods, the RMTileCache for an RMMapView can be configured to keep map tiles around based on their count or based on their age in the cache.
Caching based on previous user interaction
Tiles are automatically cached once they are downloaded for display based on the user's panning and zooming of the map. For example, if a user views the map, then zooms out, then zooms back in later when offline, the original tiles will be present in cache and will display without need for a network connection.
Proactive background caching for certain map regions
Using the RMTileSourceBackgroundDelegate protocol, the developer can enable the user to download a certain bounding box and zoom range in the background in advance of actually displaying them on screen. Callbacks trigger, allowing the developer to report progress to the user or even to cancel a download in progress. Tiles that already exist in cache will be skipped over during this background download instead of re-downloaded.
MBTiles prepackaged tiles
Using the MBTiles format for map tile storage, developers can build apps that read the tiles straight out of the MBTiles file and do not ever need a network connection. Since MBTiles is an open format, files can be created manually or with TileMill, as well as many other applications and utilities.
For more on any of these offline methods, see the full API reference for the MapBox iOS SDK.
Other APIs
What is the Static API?
The API can generate static images of maps for use on the web and mobile devices. Each static map image counts as 1 map view. For more information, see the developer documentation.
Does MapBox have a Geocoding API?
We provide a light Gecoding API with resolution down to cities, neighborhoods, and zip codes, but not street addresses. It's currently stable, so you're fine to build against it - no breaking changes are expected anytime soon, and you will be notified of any changes.
You are allowed 3x as many geocoding requests as your are on your mapbox plan.
Will you be building an Android SDK?
There are no plans at the moment - if we do write something, it'd likely just be based on one of the decent open-source SDKs, like OSMDroid. Here's an article about supporting MBTiles on Android with OSMDroid.
MapBox Company Information
Are you hiring?
Please visit this page for information about working with us. You can send an email to jobs@developmentseed.org to start this conversation.
Where can I find press resources?
You can find out how to get in touch with us, download our logo, and see recent news about MapBox on our Press page.
MapBox Satellite Information
Can I trace Mapbox Satellite in OpenStreetMap?
Yes. Everything in MapBox Satellite is traceable in OpenStreetMap, and now any edits to OpenStreetMap show up on MapBox Streets within 5 minutes.
What is the European coverage for MapBox Satellite?
Our Cloudless Atlas and main MapBox Satellite layer provides continuous coverage up to zoom level 12 globally. We are gradually rolling out high resolution aerial imagery through our partnership with Digital Globe.
We currently have full coverage up to zoom level 19 for the following countries: Austria Belguim, Denmark, France, Germany, Ireland, Italy, Luxembourg, Malta, Netherlands, Portugal, Spain, Switzerland, and the United Kingdom.
Western Europe Aerial Coverage
We are planning an aggressive rollout of imagery for the rest of the world, giving us an eventual zoom level 17 coverage for the entire planet.
When will you provide updated imagery for my hometown/area of interest?
We are actively improving our MapBox Satellite layer. As soon as there’s better imagery available and we have a chance to check it for quality! If you feel we’re not using the best open data possible for a given area, feel free to get in touch with specific links to the data source and we’ll look into it.
What are the sources for the imagery in MapBox Satellite?
We use many sources. From zoom level 1-8, we use data from NASA MODIS satellites, which we’ve de-clouded. As you zoom in up to zoom level 12, our imagery is from NASA/USGS Landsat. For the closest levels, zooms 13-19 for the continental US and Western EU, we partnered with Digital Globe, to provide the newest, and highest resolution imagery available.