MapBox Help

Maps

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

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

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

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

Enabling satellite imagery

Enable the Satellite layer to add aerial imagery to your map. Read the announcement blog post for information about coverage.

Enabling terrain visualization

Click the mountain button next to the Areas layer to enable a terrain visualization featuring hillshading and elevation contour lines.

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

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.

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

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

3. Once your layer is uploaded click View to preview the map on MapBox.

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

Adding custom layers

1. Click the Add layer button under the Layers tab of your map.

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

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

Adding markers

1. Open or create a map.
2. Click the Markers tab of your new map.
3. Give your first marker a title and description. The description may contain basic HTML.
4. Click Place on map, and then click again on the map at the location you want to add the marker.
5. Click on the pen to choose the marker’s size, color and symbol.
6. Add additional markers by clicking the Add marker button.

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

Provide proper attribution when required

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.

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

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

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

1. 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.
2. Maps that tell the whole story. If your map can stand alone embeds give you a simple, direct wrapper around your content.
3. 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

1. Custom styling. You need tooltips, legends, or controls that all match your website or application’s look and feel.
2. Animation, layer switchers, and more. You need to integrate Easey or some other advanced map manipulations to tell your story effectively.

JavaScript API

Developers can use mapbox.js for custom integration of maps into their site. Take a look at the examples and API.

Bring Your Own 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.

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.

iOS SDK

The MapBox iOS SDK provides a complete toolset for building native iOS mapping applications. Take a look at the guide, API reference and example apps.

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

How frequently is MapBox Streets updated?

MapBox Streets is re-rendered with up to date OpenStreetMap data roughly once per month.

How can I report a problem with a map?

Use the map feedback form to let us know.

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.

Deleting a map

You can permanently delete a map from your account page. Find the map you want to delete and click the delete button.

Accounts

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.

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.

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

• American Express
• Visa
• MasterCard

On a case-by-case basis, we offer invoicing for annual Plus and Premium subscriptions. Contact support for details.

How do I update my payment information?

1. Login and navigate to the billing page.
2. Under Payment information click Update and provide new payment card information securely.

How do I cancel?

1. Login and navigate to the change plan page.
2. Click Cancel.

How can I upgrade or downgrade my plan?

1. Login and navigate to the change plan page.
2. 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 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.

1. Login to your account and delete each of the maps you no longer wish to use.
2. Navigate to the change plan page.
3. Click Delete account.

Completing your profile

1. Login and navigate to the account settings page.
2. 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.

Changing your password

1. Login and navigate to the password settings page.
2. Click the Account link on your user toolbar to view your Account settings.
3. Enter your new password and confirm it, then click Change password.

Changing your email address

1. Login and navigate to the account settings page.
2. Click the Account link on your user toolbar to view your Account settings.
3. Enter your new email address and click Update email.

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

Checking your account usage

1. Login and navigate to the billing page.
2. Your account page shows you your current MapBox Hosting plan and your account’s storage and transfer usage.

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.

1. Login and navigate to the billing page.
2. Click the Optional Contact Info button.
3. Enter the relevant information in the text field and click Update Information.
4. Your statements will now show the new information.

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.

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

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.

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