In this tutorial, we will learn how we can create a scatter on a map box using the scatter_mapbox() function. The Mapbox scatter creates a mark for each row in a Data Frame as a symbol on a map.

Let’s discuss.

Function Syntax and Parameters

The function takes on the following syntax:, lat=None, lon=None, color=None, text=None, hover_name=None, hover_data=None, custom_data=None, size=None, animation_frame=None, animation_group=None, category_orders=None, labels=None, color_discrete_sequence=None, color_discrete_map=None, color_continuous_scale=None, range_color=None, color_continuous_midpoint=None, opacity=None, size_max=None, zoom=8, center=None, mapbox_style=None, title=None, template=None, width=None, height=None)

The function parameters are as follows:

  1. data_frame – Specifies the data frame containing the data to be plotted on the map.
  2. lat – Sets the values used to position the marks according to the latitude on the map.
  3. lon – Similar to lat but the values of this parameter are used to position the marks along the longitude on the map.
  4. color – Specifies the values used to assign a unique color to the marks of the scatter.
  5. text – Sets the values used as text labels.
  6. title – Defines the title for the figure.
  7. width/height – Specifies the width and height of the figure in pixels.


The following code shows how to create a simple scatter mapbox. This may require you to have a Mapbox account and access token.

import as px
import pandas as pd
df = pd.read_csv("worldcities.csv")
lat =
lon = df.lng
city_name =

fig = px.scatter_mapbox(df, lat=lat, lon=lon, labels=city_name)

In the given code, we start by importing the Plotly express module as px. We also import the Pandas which allows us to read the CSV data.

The next step is to read the access token for the Mapbox API. You will get this token once you signup for the mapbox.

Save the access to a file that ends in .mapbox_token and read it using the open function.

Next, we load the CSV file containing the data. You can access this file in the following resource:

The next step is setting the latitude, longitude, and city name from the DataFrame. Finally, we create the scatter mapbox of the world cities. The resulting figure is as shown in the following:

To get a better view at default, we can use the zoom parameter as shown in the following:

fig = px.scatter_mapbox(df, lat=lat, lon=lon, labels=city_name, zoom=1)

The given code sets the zoom level to 1, allowing you to view the entire map. This view may vary depending on your environment and screen ratio.

To set a different color for each city, set the color parameter:

fig = px.scatter_mapbox(df, lat=lat, lon=lon, labels=city_name, zoom=1, color=city_name)

Note: This process may take a long time to process depending on the DataFrame size.


This article describes a simple method of creating a scatter mapbox using the mapbox API and Plotly scatter_mapbox() function. Check the document for more.

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list