Embeds are a quick way to get your MapBox maps onto webpages. Custom usage of the API in applications, on the other hand, gives you full control over the styling, workflow, and many other aspects of your map. Here are some guidelines to help you decide which approach is right.

1. Some examples

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

2. 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 styles
Legends	Yes	Yes + custom styles
Google Maps baselayer	Yes	Yes + custom styles
Share links	Yes	Yes
Animation with Easey	No	Yes
Dynamic layer switcher	No	Yes
Custom tooltips	No	Yes

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