Google Maps provides a $200 monthly credit, but beyond that, usage is billed per request. For applications like logistics, ride-hailing, or fleet tracking – where thousands of requests are made daily – costs can grow quickly depending on which APIs you use.

OpenStreetMap (OSM) offers a different approach. Instead of charging for access to map APIs, it provides free, open geographic data that you can build on.

In this guide, you'll learn what OpenStreetMap is, how it differs from Google Maps, and how to integrate it into a React application using Leaflet.

What We'll Cover:

1. What is OpenStreetMap?

2. Why Choose OpenStreetMap Over Google Maps?

3. Understanding the OpenStreetMap Ecosystem

   • Data Layer (OpenStreetMap)

   • Rendering Layer (Leaflet, MapLibre)

   • Services Layer

   • How Everything Works Together

4. How to Integrate OpenStreetMap in React with Leaflet

5. How to Add Geocoding with Nominatim

6. Advanced Features

7. When to Choose OpenStreetMap vs Google Maps

8. Wrapping Up

What is OpenStreetMap?

OpenStreetMap is a free, open, and community-driven map of the world. Anyone can contribute to it, and anyone can use it.

Unlike Google Maps, which gives access through controlled APIs, OpenStreetMap gives you access to the underlying geographic data itself.

This data is structured in three main ways:

1. Nodes: single points (for example, a bus stop or a tree)

2. Ways: lines or shapes made up of nodes (like roads or buildings)

3. Relations: groups of nodes and ways that define more complex things (like routes or boundaries)

Each of these elements includes tags (key-value pairs), such as:

highway=residential
name=Allen Avenue

So instead of just displaying a map, OpenStreetMap lets you work with structured geographic data.

The Open Database License (ODbL)

OpenStreetMap data is licensed under the ODbL. This means:

• You can use it for commercial or personal projects

• You must give proper attribution

This makes it especially useful for developers who want clarity around data ownership.

Why Choose OpenStreetMap Over Google Maps?

Cost

OpenStreetMap data is free to use. But it's important to be precise here: OpenStreetMap removes licensing costs, but not infrastructure costs.

You may still need to pay for:

• Tile hosting

• Geocoding services

• Routing engines

Control

With Google Maps, you can't modify the data, and you rely entirely on Google's APIs

But with OpenStreetMap, you can download and store the data, modify it, and build custom solutions on top of it.

Customization

OpenStreetMap gives you more flexibility:

• You control how maps are rendered

• You can choose or build your own map styles

• You can create domain-specific maps

Adoption

OpenStreetMap is widely used. Companies like Meta and Microsoft contribute to it, and many platforms rely on it directly or indirectly.

This shows that the ecosystem is mature and reliable.

Understanding the OpenStreetMap Ecosystem

A common mistake is to think that OpenStreetMap works like a single API. It doesn't.

Instead, it works as a set of layers, where each layer handles a different responsibility.

Data Layer (OpenStreetMap)

This is the foundation. It contains all the raw geographic data:

• Roads

• Buildings

• Landmarks

• Boundaries

This is what you are ultimately working with.

Rendering Layer (Leaflet, MapLibre)

Raw data isn't visual. It needs to be turned into something users can see.

There are two main approaches:

1. Raster tiles (used by Leaflet): pre-rendered images

2. Vector tiles (used by MapLibre): raw geometry styled in the browser

Leaflet uses raster tiles by default, which makes it simple and fast to start with.

Services Layer

This is what makes your map interactive. Geocoding converts addresses into coordinates, while reverse geocoding converts coordinates into addresses.

Routing calculates directions between points, and tile servers provide the actual map visuals.

How Everything Works Together

When a user searches for a place:

1. The user enters a location

2. A geocoding service converts it into coordinates

3. The map updates its position

4. A tile server provides the visual map

Each part is separate, but they work together to create the full experience.

How to Integrate OpenStreetMap in React with Leaflet

Let's build a simple map.

Step 1: Create a React App

npm create vite@latest osm-app -- --template react
cd osm-app
npm install

Step 2: Install Dependencies

npm install leaflet react-leaflet
npm install --save-dev @types/leaflet

Step 3: Import Leaflet CSS

import 'leaflet/dist/leaflet.css';

This is required for the map to display correctly.

Step 4: Create a Map Component

import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';

function Map() {
  const position = [51.505, -0.09]; // latitude, longitude

  return (
    <MapContainer
      center={position}
      zoom={13}
      style={{ height: '100vh' }}
    >
      <TileLayer
        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
      />
      <Marker position={position}>
        <Popup>Hello from OpenStreetMap</Popup>
      </Marker>
    </MapContainer>
  );
}

export default Map;

Let's break down the important parts here:

MapContainer initializes the map.

• center is where the map starts

• zoom is how close the view is

• style must include height, or the map won't show

TileLayer defines where the map visuals come from.

• {z} is the zoom level

• {x}, {y} are the tile coordinates

• {s} is the subdomain

Each tile is a small image (usually 256×256 pixels), and Leaflet combines them to form the full map.

Marker adds a point on the map at a specific coordinate.

Popup displays information when the marker is clicked.

Important note:

The default OpenStreetMap tile server:

https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

is meant for learning, demos, and low-traffic apps. For production, you should use a dedicated provider or your own tile server.

How to Add Geocoding with Nominatim

Nominatim is OpenStreetMap's geocoding service. It allows you to convert addresses into coordinates and coordinates into readable locations.

Custom Hook for Geocoding

import { useState } from 'react';

export function useGeocoding() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const searchAddress = async (query) => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch(
        `https://nominatim.openstreetmap.org/search?q=${encodeURIComponent(query)}&format=json&limit=5`,
        {
          headers: {
            'User-Agent': 'YourAppName/1.0'
          }
        }
      );

      if (!response.ok) {
        throw new Error('Request failed');
      }

      const data = await response.json();
      setLoading(false);
      return data;
    } catch (err) {
      setError(err.message);
      setLoading(false);
      return [];
    }
  };

  return { searchAddress, loading, error };
}

In this code:

• useState manages loading and error states

• encodeURIComponent ensures safe URLs

• User-Agent is required by Nominatim

• response.json() converts response into usable data

Nominatim returns coordinates as strings, so you have to convert them before using them.

Important Usage Rules

The public Nominatim service:

• Allows about 1 request per second

• Requires proper identification

• May block excessive usage

You should debounce user input, cache results, and avoid repeated requests.

Creating a Search Component

The search component lets users type an address or place name and get matching locations via Nominatim. It includes a text input and a submit button.

When the form is submitted, it calls our searchAddress function (from the useGeocoding hook), which fetches up to 5 address results. These results are displayed below the input as clickable items.

When the user clicks a result, the component parses the returned latitude and longitude into numbers and passes them (along with a display name) up to the parent component via the onLocationSelect callback. This will allow the parent (for example, the map) to update its center based on the chosen location.

function SearchBox({ onLocationSelect }) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const { searchAddress, loading } = useGeocoding();

  const handleSearch = async (e) => {
    e.preventDefault();
    if (!query.trim()) return;

    const data = await searchAddress(query);
    setResults(data);
  };

  const selectLocation = (result) => {
    onLocationSelect({
      lat: parseFloat(result.lat),
      lon: parseFloat(result.lon),
      name: result.display_name
    });
  };

  return (
    <div>
      <form onSubmit={handleSearch}>
        <input
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          placeholder="Search location"
        />
        <button type="submit">
          {loading ? 'Searching...' : 'Search'}
        </button>
      </form>

      <div>
        {results.map((result) => (
          <div key={result.place_id} onClick={() => selectLocation(result)}>
            {result.display_name}
          </div>
        ))}
      </div>
    </div>
  );
}

Key concepts here:

• useState stores the current input (query) and the array of search results.

• e.preventDefault() stops the form submission from reloading the page.

• Calling searchAddress(query) fetches geocoding results from Nominatim.

• parseFloat() converts the returned lat/lon strings into JavaScript numbers before using them.

• onLocationSelect is a callback prop that sends the selected coordinates and name back to the parent component (for example to update the map).

Advanced Features

We can further extend the map app by adding more advanced functionality. For example:

Routing (OSRM, GraphHopper)

You can integrate turn-by-turn routing on your map. A common solution is to use a library like Leaflet Routing Machine, which supports OSRM out of the box and has plugins for GraphHopper. This adds a route UI control where users enter start and end points, and the library fetches a route from one of these engines to draw on the map.

Custom Tile Providers (Carto, MapTiler, and so on)

Instead of the standard tile.openstreetmap.org, you can use hosted tile services that offer OSM-based maps. For example, Carto and MapTiler both provide tile APIs (often with custom style options and higher usage limits).

Carto, MapTiler, and similar services are listed among the providers that allow free usage of OSM tiles. By using a custom tile provider, you gain flexibility in map design and avoid hitting the public server’s limits.

Vector Maps (MapLibre GL JS)

You can switch from raster tiles to vector tiles for even richer interactivity. Vector tiles send raw map data (geometries and attributes) to the client, which are then rendered in the browser. This allows dynamic styling and advanced features: for instance, you can change the map’s theme on the fly (for example, switch to a “dark mode” style at night) or highlight certain features like bike lanes more prominently.

Libraries like MapLibre GL JS (the open-source successor to Mapbox GL) can display OSM vector tiles with highly customizable styles and smooth zooming/rotation. This makes your map more responsive and adaptable to different use cases.

When to Choose OpenStreetMap vs Google Maps

Choose OpenStreetMap when:

• You need flexibility

• You want to reduce costs at scale

• You want control over data

Choose Google Maps when:

• You want an all-in-one solution

• You need features like Street View

• You want minimal setup

Wrapping Up

OpenStreetMap offers a powerful alternative to Google Maps for developers who need cost control, data ownership, and customization. While it requires understanding different components, the flexibility it provides is worth the learning curve.

I'm a fan of musical theatre. The last show I saw in London's West End before Covid was Dear Evan Hansen. It's a show about teen suicide, parenting and social media (sounds a blast, eh?).

The show opens with a song sung by two mothers, asking if anyone has a map.

Does anybody have a map?
Anybody maybe happen to know how the hell to do this?
I don't know if you can tell
But this is me just pretending to know

Maps are pretty amazing pieces of technology. They provide a way to get an overview of what you know and what you don't know.

As tools for navigation, they allow us to be able to plot and plan routes. You can see which parts of the journey are going to be more challenging and which you don't know enough about.

As tools for discussion, they help reduce confusion and increase clarity. Which hill are you talking about exactly? How far away is that? How long will it take to get there?

As tools for discovery, they help show where more investigation is needed. In ancient times, dragons or sea monsters were often drawn on the parts that were unknown. Our satellite imagery is more accurate but can also make us think we know everything.

Carta Marina - map of the Nordic countries with sea monsters to the west

The moms in the song wanted some way to navigate through parenting, to identify smooth paths and rough terrain.

So how does this relate to web development?

The FreeCodeCamp Curriculum

freeCodeCamp Certifications

The freeCodeCamp curriculum is pretty great. It traces an outline of the most important aspects of web development today.

The way I've placed each of the certifications in the image above suggests they are separate and distinct. In fact, they overlap and use core pieces of knowledge throughout.

Read through the lesson titles and headings. They draw out the high notes - frontend, backend, algorithms, data, HTML, CSS, JavaScript, Python and more. Seen together, these draw a map of the space.

Possible map of the FCC curriculum

There are other maps around. The web-developer roadmaps that Kamran Ahmed has been keeping updated are pretty epic. These have the advantage that they look a bit more like maps, but they can feel overwhelming.

What's the Purpose of a Map?

I saw earlier versions of Kamran's roadmaps a few years ago and they made me feel a bit overwhelmed. There was so much I needed to know to become a developer. At least, that was how it felt.

Over time, though, I've begun comparing it to flicking through an atlas or Google maps. I love seeing how countries change as you cross a river or mountain range. I enjoy tracing rivers over whole continents and imagine walking the mountain ranges.

I don't feel inadequate that I haven't visited all of these countries or that I can't remember every country or every capital. Instead, I feel empowered and excited by knowing roughly where countries are and how they fit together.

Map of the world

I live in Brighton, and if I want to meet a friend for coffee, then a street map is going to be much more useful.

Street map of central Brighton

But, it we were going for a walk in the countryside, tracing a river for example, then yet another type of map is needed.

Map of the River Frome

I find that this is the same for any learning project. For web development, you can use a map that already exists (like the freeCodeCamp curriculum or Kamran's map) or you can begin to develop your own.

Like looking at countries, you can zoom out and see how the main pieces hold together. At this level, you can see how things fit together.

Here we have large and encompassing topics like "front-end" or "quality assurance". We don't need to know everything to about these topics but we can see how they relate to others.

Like looking at cities, you can zoom in to see how a particular technology works. How does JavaScript work? What is the syntax? What are the rules and patterns?

And like tracing rivers, you can see how a practice or convention is handled in the front-end, back-end and everywhere in between.

Here we might think about how data flows between the different parts of a web application. We can imagine the journey of the data from the user, to the front-end, to the database and back out again.

How to Become a Well-equipped Explorer

I'm a largely self-taught developer. Early in my learning career, I would hear whispers of an interesting, cool or new technology and dive in. I'd read books, do tutorials and build small example projects. However, they didn't connect together in my mind.

To continue with the mapping metaphor, I was being teleported randomly into a city, exploring and then leaving again. Over years, I had ideas about lots of cities and no idea how they fit into countries and how the rivers and landscapes linked them together.

It was only when I had a map of the space that I understood how the knowledge I had fit together. I could see where the gaps in my understanding were and direct my efforts in the right direction.

I realised that I didn't need to explore the whole world but I could have an awareness of what was out there.

What about you?

What maps are you using to help you with your development journey? Have you drawn a dragon over back-end technologies and decided you don't want to go near them? Or maybe there is a sea monster hovering over CSS or algorithms?

Excellent developers are always learning. They are studying their maps and deciding where they'd like to explore next.

You don't have to know the whole world but knowing what you know (and what you don't) can help take your skills to the next level.

Note: As of July 2022, GraphCMS is now Hygraph.

• What are we going to build?
• Step 1: Creating a new app with Gatsby Starter Leaflet
• Step 2: Creating and managing a list of travel locations with GraphCMS
• Step 3: Querying our GraphCMS location data with Gatsby and GraphQL
• Step 4: Creating a bucket list of destinations and adding them to the map
• What else other features can we add to our app?
• Want to learn more about maps?

What are we going to build?

We’re going to build a mapping app with Gatsby managed by a CMS that will both display markers on a map and show our locations in a simple text-based list for our bucket list locations.

Demo of a Travel Bucket List mapping app

We’ll spin up the app with a Gatsby Starter for Leaflet and then we’ll use GraphCMS to create and manage the list of locations for our map!

Woah, a mapping app?

Yup. If you haven't played with maps before, don't be discouraged! It's not as bad as you probably think. If you'd rather start with mapping basics, you can read more about how mapping works first.

Step 1: Creating a new app with Gatsby Starter Leaflet

We’ll start off with Gatsby Starter Leaflet. This is going to give us a basic React application with our mapping tools already built in.

Creating a new Gatsby app with Gatsby Starter Leaflet

To get started, navigate to where you want to create your new app and run:

gatsby new my-travel-bucket-list https://github.com/colbyfayock/gatsby-starter-leaflet

Note: you can replace my-travel-bucket-list with whatever you want. This will be used to create the new folder for the app.

Once you run that, Gatsby will pull down the Starter and install the dependencies. After it’s complete, navigate to that directory and run the development command:

cd my-travel-bucket-list
yarn develop
# or
npm run develop

Once it’s finished location, your app should be ready to go!

Cleaning our some demo code

Because we’re using a Starter, it has a little bit of demo code. Let’s clean that out to avoid any confusion.

Open up the src/pages/index.js file.

First, remove everything inside of mapEffect except the first line and set up an alias for leafletElement to map:

async function mapEffect({ leafletElement: map } = {}) {
  if ( !map ) return;
}

With that gone, we can remove the markerRef definition at the top of the IndexPage component, remove the ref={markerRef} prop from our <Marker> component, and the useRef import next to React.

Now, we can remove all of the variables that start with popup and time, including:

• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• popupContentHello
• popupContentGatsby

Lastly, you can remove all of the following lines:

import L from 'leaflet';
...
import { promiseToFlyTo, getCurrentLocation } from 'lib/map';
...
import gatsby_astronaut from 'assets/images/gatsby-astronaut.jpg';
...
const ZOOM = 10;

Once done, we should be ready to go with a basic app with a map!

New app with Gatsby Starter Leaflet

Follow along with the commit!

Step 2: Creating and managing a list of travel locations with GraphCMS

Creating a GraphCMS account

To get started with GraphCMS, you’ll need an account. I’m not going to walk you through this part, but the good news is they have a generous free tier that makes it easy to sign up for us to use for our demo!

Sign up for GraphCMS

Alternatively, if you already have an account, you can make sure you’re logged in.

Creating a new GraphCMS project

Once logged in, we’ll want to create a new project. We’re going to create one manually, so once at the GraphCMS Dashboard, select Create new project:

Creating a new project in GraphCMS

Here, you can enter whatever you’d like for the Name and Description such as:

• Name: My Travel Bucket List
• Description: The locations that I want to travel to some day!

Below that you’ll see a map where you’ll select a Region. This is where your database data will live, so while it probably doesn’t matter too much for our purposes, you can choose the one that’s closest to you.

Configuring a new project in GraphCMS

After you select your options, go ahead and click Create Project.

Selecting the Personal plan in GraphCMS

Next, you’ll be presented with billing options. Since we’re just creating a demo, under Personal select Continue at which point we’ll be dropped into our new GraphCMS project dashboard.

Creating a new Content Model Schema with GraphCMS

In GraphCMS, a Content Model refers to a specific type of data that has specific properties associated with it. In our case, our Model will be a Destination, which will be defined by a Name and a Location.

First, navigate to the Schema section of GraphCMS in the left sidebar and select Create Model.

Creating a new Schema Model in GraphCMS

Once selected, you’ll see a popup that asks for a bit more information. Here, you can type in “Destination” as the Display Name, which will also fill in most of the other fields. We’ll leave those as is.

Configuring a new Model in GraphCMS

Feel free to add a description if you’d like, but it’s not required. Then select Create model.

Now that we have our Model, we need our properties.

First, select Single line text in the right list of fields and add a Display Name of “Name”. This will also fill out App Id which you can leave as is. Then click Create.

Adding and configuring a new text field in GraphCMS

Next, scroll down in the field options on the right and under Location select Map. Add “Location” as the Display Name, which will set the App Id as “location” which you can leave as is. Then same as before, click Create.

Adding and configuring a new map field in GraphCMS

Now we have a Content Model which we’ll use to create our locations!

Destination content Model in GraphCMS

Creating our locations

Finally, let’s create our locations. Navigate over to Content in the GraphCMS dashboard, make sure you’ve selected Destination under System (should be the only one), and select Create New.

Create new Destination Content in GraphCMS

Now we can start adding all of our locations! First, add the name of your location in the Name field, then you can use the Search box under Location to find that location on the map.

Adding a new Destination Content item in GraphCMS

Once you’re good, hit Save and publish. This will create your first location!

Follow those same steps and create as many locations as you want.

List of Destination Content items in GraphCMS

We’ll use these for our map and bucket list.

Step 3: Querying our GraphCMS location data with Gatsby and GraphQL

Now that we have our locations, let’s use them!

Adding a plugin to Gatsby to query our GraphQL data

First, we need to add a new plugin to our Gatsby project to query our GraphQL data. In your terminal make sure your development server isn’t running and run:

yarn add gatsby-source-graphql
# or
npm install gatsby-source-graphql

Next, open up your gatsby-config.js file in the root of your project and add the following to your plugins:

{
  resolve: 'gatsby-source-graphql',
  options: {
    typeName: 'GCMS',
    fieldName: 'gcms',
    url: '[API ENDPOINT]',
  }
}

This will be what sources our data from GraphCMS, but we need an endpoint.

Finding our API endpoint for GraphCMS

Open back up your browser and head over to your GraphCMS project. After selecting Settings in the left navigation, select API Access.

API Access in GraphCMS

Before we copy our API Endpoint, first we need to update our permissions so we can query our API. Under Public API Permissions, check the box next to Content from stage Published and click Save.

Configuring API permissions in GraphCMS

Next, copy the URL under Endpoints:

Copying API Endpoint in GraphCMS

And paste that in to your gatsby-config.js file that we modified above:

{
  resolve: 'gatsby-source-graphql',
  options: {
    typeName: 'GCMS',
    fieldName: 'gcms',
    url: 'https://[region-id].graphcms.com/v2/[project-id]/master',
  },
},

Note: your URL will have actual values inside of [region-id] and [project-id].

Save your gatsby-config.js file and start your development server backup (yarn develop) and we’re ready to go!

Querying our locations via GraphQL

Finally, let’s actually query our data so that we’ll be able to use it in our app.

We’re going to create a new React Hook that we’ll be able to use to grab our locations anywhere within our app.

Under src/hooks/index.js, add the following line to the existing list:

export { default as useDestinations } from './useDestinations';

This will allow us to more conveniently import our hook which we’ll create next.

Under src/hooks, create a new file useDestinations.js and paste in this code:

import { graphql, useStaticQuery } from 'gatsby';

export default function useDestinations() {
  const { gcms = {} } = useStaticQuery( graphql`
    query {
      gcms {
        destinations {
          id
          name
          location {
            latitude
            longitude
          }
        }
      }
    }
  ` );

  let { destinations } = gcms;

  return {
    destinations,
  };
}

Here, we’re:

• Importing the graphql and useStaticQuery utilities from Gatsby
• We’re creating a new function (or hook) that is exported by default
• In that function, we’re using useStaticQuery to create a new GraphQL query which asks GraphCMS to return the data structure we defined.
• That query returns a value which we destructure immediately to grab the gmcs object
• We destructure destinations from gmcs and return it as part of a new object from our hook

With this, we can now use our hook anywhere in our app!

Head over to your src/pages/index.js file, first import our new hook:

import { useDestinations } from 'hooks';

And at the top of the IndexPage component, query our data:

const { destinations } = useDestinations();

This puts all of our locations into the destinations variable. We can test that this works by console logging it out:

console.log('destinations', destinations);

And once we open up our browser and look in our web developer tools console, we can see our location data!

Logging destinations data to the web console

Step 4: Creating a bucket list of destinations and adding them to the map

We’re going to start with creating a simple text list of our destinations. This will let us see all of our destinations in an easy to read format.

Creating a text list of our destinations

Inside of our IndexPage and above “Still Getting Started?”, let’s add the following code:

<h2>My Destinations</h2>
<ul>
  { destinations.map(destination => {
    const { id, name } = destination;
    return <li key={id}>{ name }</li>
  })}
</ul>

This code:

• Adds a new header for our list
• Creates a new unordered list
• Loops through our destinations and creates a new list item for each destination that include’s the location’s name

Once we hit save and reload, we should see our list under our map!

New basic list of destinations in the app

The list looks a little odd though right? We probably want to format it a little better to fit into the page.

Open up src/assets/stylesheets/pages/_home.scss and inside of the .home-start class, add:

.home-start {

  ...

  ul {
    list-style: none;
    padding: 0;
    margin: 1.2em 0;
  }

Let’s also modify the h2 to space things out a little better:

.home-start {

  ...

  h2 {

    margin-top: 2em;

    &:first-child {
      margin-top: 0;
    }

  }

Once you hit save and reload, it should look a little better.

Destinations in the app with cleaned up styles

Feel free to make additional changes, but we’ll leave it there for now.

Adding our destinations to the map

Now we can finally add our destinations to the map!

Inside of our <Map> component, we already have a <Marker>. This allows us to easily add a marker to the map given a position. We’ll take this concept and combine it with our text list to add our locations to the map.

Let’s update our <Map> code to match the following:

<Map {...mapSettings}>
  { destinations.map(destination => {
    const { id, name, location } = destination;
    const position = [location.latitude, location.longitude];
    return <Marker key={id} position={position} />
  })}
</Map>

Here we:

• Loop through our destinations to dynamically create a new list of components inside our <Map>
• Inside each loop instance, we destructure our date from destination
• We create a new position array with the latitude and longitude
• Create a new Marker where we use our position to add it to the map

This gives us our markers on the map!

Markers for each destination in the mapping app

But we want to know what each of those locations are, so let’s also add a popup to each marker that will show the name.

First, we need to import Popup from react-leaflet:

import { Marker, Popup } from 'react-leaflet';

Then, let’s update our <Marker> component to return:

return (
  <Marker key={id} position={position}>
    <Popup>{ name }</Popup>
  </Marker>
);

And once we save and open back up our map, you can now click on each marker and see our destinations name!

Popup for each destination marker in the mapping app

Before we’re done, center the map

Previously, our demo map centered on Washington, DC. Let’s update that to the center of the world since our map doesn’t focus on the United States.

Update the LOCATION variable to:

const LOCATION = {
  lat: 0,
  lng: 0,
};

And with that, we have our map!

Final mapping app with markers and popups for each destination

Follow along with the commit!

What else other features can we add to our app?

Add a way to check off each location

Inside GraphCMS, you can add a new field to your Destination content model that allows you to select whether you visited each location or not.

With this value, we can add it to our query and update our map with some kind of indicator like a checkmark to show that we’ve checked it off our bucket list!

Customize your map background styles

We’re using a public version of OpenStreetMap which is open source, but Mapbox offers some cool maps we can use to make it look a little more impressive.

If you want to get started changing your map styles, you can check out this other walkthrough of mine to learn how to use Mapbox.

Check out the blog post or watch the video!

Style the map markers with a custom image

You can check out my video walk through on how to change the markers to a custom image.

Take that a step further and use the feature above to dynamically show a different marker image when you’ve checked off a location.

Check out the video on Egghead.io!

Want to learn more about maps?

Check out some of my other tutorials and videos:

• Mapping with React Leaflet (egghead.io)
• Mapping Apps with React, Gatsby, & Leaflet (youtube.com)
• How to create a Coronavirus (COVID-19) Dashboard & Map App with Gatsby and Leaflet (colbyfayock.com)
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet (colbyfayock.com)
• How to build a mapping app in React the easy way with Leaflet (colbyfayock.com)
• Anyone Can Map! Inspiration and an introduction to the world of mapping (colbyfayock.com)

What’s on your travel bucket list?

Let me know on Twitter!

Author's note: Similar to before, this dashboard is meant to be a demo and proof of concept for using real world data to build a dashboard. While this data should be accurate per the NovelCOVID API, I would recommend using tools like the Johns Hopkins University dashboard for complete and accurate analysis. Stay home and be safe! ❤️

• What are we going to build?
• What do we need before we get started?
• Step 1: Update how we fetch our data and fetch the statistics
• Step 2: Adding statistics to our dashboard
• Step 3: Make the data human friendly
• Step 4: Add the Last Updated date
• What can I do next?

What are we going to build?

We're going to be extending our original map demo with some basic statistics that we can retrieve from the NovelCOVID API. To get an idea, here's my demo I'm basing this off of.

Coronavirus (COVID-19) map demo with dashboard statistics

While you're not required to have completed Part 1 to apply these concepts, it definitely helps, and it lets you set up a map for your dashboard. If you'd like to start there, which I recommend, check out How to create a Coronavirus (COVID-19) Dashboard & Map App with Gatsby and Leaflet first.

Woah, a mapping app?

Yup. If you haven't played with maps before, don't be discouraged! It's not as bad as you probably think. If you'd rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

For this walkthrough, you pretty much need a React app in some form. I'll be working with the dashboard we previously built in my last walkthrough that includes a map of the cases of the Coronavirus (COVID-19) per country.

Coronavirus (COVID-19) map dashboard

I recommend starting with the previous tutorial, but if you want to skip the map and start fresh, the easiest way would probably be to use Create React App, Gatsby, or Next.js.

Step 1: Update how we fetch our data and fetch the statistics

To get started with our statistics dashboard, we're going to do a little prep work by changing how we're fetching the data. The goal here, is we're going to wrap our request logic in a reusable way so that we can use it for both our countries data and our new statistics data.

Creating a new React hook to fetch data

Diving in, the first we'll do is create a new React hook that will serve as how we fetch the data. To get started, create a new file in your hooks directory called useTracker.js and add a line inside of hooks/index.js to export it:

// New file src/hooks/useTracker.js
// This will be empty for now

// Inside hooks/index.js
export { default as useTracker } from './useTracker';

Inside of our useTracker.js file, we're going to set up our request logic. This is a long file, so make sure you copy and paste the entire thing before we walk through what it does:

import { useEffect, useState } from 'react';
import axios from 'axios';

const API_HOST = 'https://corona.lmao.ninja/v2';

const ENDPOINTS = [
  {
    id: 'all',
    path: '/all',
    isDefault: true
  },
  {
    id: 'countries',
    path: '/countries'
  }
]

const defaultState = {
  data: null,
  state: 'ready'
}

const useTracker = ({ api = 'all' }) => {

  const [tracker = {}, updateTracker] = useState(defaultState)

  async function fetchTracker() {
    let route = ENDPOINTS.find(({ id } = {}) => id === api);

    if ( !route ) {
      route = ENDPOINTS.find(({ isDefault } = {}) => !!isDefault);
    }

    let response;

    try {
      updateTracker((prev) => {
        return {
          ...prev,
          state: 'loading'
        }
      });
      response = await axios.get(`${API_HOST}${route.path}`);
    } catch(e) {
      updateTracker((prev) => {
        return {
          ...prev,
          state: 'error',
          error: e
        }
      });
      return;
    }

    const { data } = response;

    updateTracker((prev) => {
      return {
        ...prev,
        state: 'ready',
        data
      }
    });

  }

  useEffect(() => {
    fetchTracker()
  }, [api])

  return {
    fetchTracker,
    ...tracker
  }
};

export default useTracker;

Starting from the top:

• We import our dependencies: we're going to use Reacts useEffect and useState hooks to manage our requests
• We define default constants: we have a base API endpoint for our data, a list of the available endpoints we'll use, and a state object that will store our data
• We define our useTracker hook: our hook includes one argument api that will allow us to specify which endpoint we'll use to make our request
• We set up a state instance: we'll want to keep track of our fetched data, so we create a tracker state instance that we'll be able to update
• We created an asynchronous fetchTracker function: we'll use this to make our actual request
• Inside our function: we first find the API route and create our URL, update our state instance to a "loading" state, try to make our request, catch any errors if there are any, and finally if the request is successful, we update our state with that data
• We trigger our function: using a useEffect hook, we trigger our fetchTracker function to make the request. We only have one dependency of api. This means the function will only fire the first time and any time the api value we pass in changes. We won't be changing that value, but it may be helpful in other instances if you're dynamically changing the API used
• We return our tracker: the returned object includes both our tracker data as well as our fetchTracker function that we could use to refetch the data if we'd like

And with all of that, we have a brand new hook that will fetch data from the NovelCOVID API.

Using our new tracker hook

To make use of this hook, let's jump over to src/pages/index.js, remove our axios import if it's there, and instead import our hook:

import { useTracker } from 'hooks';

With our hook, let's replace our original country data request. First, add the following to the top of the IndexPage component:

const { data: countries = [] } = useTracker({
  api: 'countries'
});

const hasCountries = Array.isArray(countries) && countries.length > 0;

This will let us fetch our country data and let us know if we have any results. Next, let's replace our original request.

Inside of our mapEffect function, let's remove the axios request in addition to the response, the destructured data object, and the hasData constant.

Code diff showing update to map effect

Then, replace hasData with hasCountries:

if ( !hasCountries ) return;

And replace data with countries in the geoJson object where we map our features:

features: countries.map((country = {}) => {

At this point, if you hit save and refresh, you shouldn't notice any difference to what you previously had.

Add a request for our stats

Now that we are using our useTracker hook to fetch our country data, let's also use that to fetch our stats.

Right next to where we set up our useTracker hook before, let's add another request:

const { data: stats = {} } = useTracker({
  api: 'all'
});

And if we add a console.log statement under to see what's inside stats:

console.log('stats', stats);

We should see our stats data object logged out!

Using console.log to show Coronavirus (COVID-19) statistics

Follow along with the commit!

Step 2: Adding statistics to our dashboard

Now that we have our data available to use, let's use it!

To get started adding our statistics to the dashboard, let's create a data structure that will allow us to easily configure the data we want to use.

To do this, let's first create a new array called dashboardStats below hasCountries at the top of the page component:

const dashboardStats = [];

Inside this array, let's add some new objects that specify our data that we're pulling from the stats object we requested. To start, let's try to add:

const dashboardStats = [
  {
    primary: {
      label: 'Total Cases',
      value: stats?.cases
    },
    secondary: {
      label: 'Per 1 Million',
      value: stats?.casesPerOneMillion
    }
  },
  {
    primary: {
      label: 'Total Deaths',
      value: stats?.deaths
    },
    secondary: {
      label: 'Per 1 Million',
      value: stats?.deathsPerOneMillion
    }
  },
  {
    primary: {
      label: 'Total Tests',
      value: stats?.tests
    },
    secondary: {
      label: 'Per 1 Million',
      value: stats?.testsPerOneMillion
    }
  }
]

The reason we're splitting this up into primary and secondary keys, is we're going to use that to differentiate between logically similar stats that we want to style a little bit differently.

_Note: if you're not familiar with the ?. syntax, it's called Optional Chaining. This allows us to chain our properties without worrying about if the objects exist. If stats is undefined, it will simply return undefined instead of throwing an error._

With our stats data, let's add the tracker to our map. Let's remove our current <Map> component and include it nested inside our tracker div in the following:

<div className="tracker">
  <Map {...mapSettings} />
  <div className="tracker-stats">
    <ul>
      { dashboardStats.map(({ primary = {}, secondary = {} }, i) => {
        return (
          <li key={`Stat-${i}`} className="tracker-stat">
            { primary.value && (
              <p className="tracker-stat-primary">
                { primary.value }
                <strong>{ primary.label }</strong>
              </p>
            )}
            { secondary.value && (
              <p className="tracker-stat-secondary">
                { secondary.value }
                <strong>{ secondary.label }</strong>
              </p>
            )}
          </li>
        );
      })}
    </ul>
  </div>
</div>

This code should be immediately following the <Helmet> component if you're following along.

To explain what we're doing:

• We're creating a "tracker" div that will organize our stats
• We move our <Map component inside of this tracker
• We create a separate section called "tracker-stats"
• Inside of this, we create an unordered list (ul)
• Inside of our list, we loop through all of our stats inside dashboardStats
• For each stat, we create a new list element (li) and include 2 optional paragraphs that includes our primary stat data and our secondary stat data

Once we reload our page, we should now see a few stats:

Adding the first statistics to the page

Now that we have our stats on our page, let's make them look like they're in a dashboard.

Let's create a new file called _tracker.scss inside of our src/assets/stylesheets/components directory. Once that file is created, additionally add it to the src/assets/stylesheets/components/__components.scss file:

@import "tracker";

With our new component style file ready to go, let's add some styles into _tracker.scss:

.tracker-stats {

  color: white;
  background-color: $blue-grey-900;
  border-top: solid 1px darken($blue-grey-900, 5);

  ul {
    display: grid;
    grid-template-columns: 1fr 1fr 1fr;
    list-style: none;
    padding: 0;
    margin: 0;
  }

}

.tracker-stat {

  font-size: 2em;
  text-align: center;
  padding: .5em;
  border-right: solid 1px darken($blue-grey-900, 5);
  border-bottom: solid 1px darken($blue-grey-900, 5);

  strong {
    font-weight: normal;
    color: $blue-grey-300;
  }

}

.tracker-stat-primary {

  margin: 0;

  strong {
    display: block;
    font-size: .5em;
  }

}

.tracker-stat-secondary {

  font-size: .5em;
  margin: .8em 0 0;

  strong {
    font-size: .8em;
    margin-left: .4em;
  }

}

Above – we're adding colors and organizational effects, such as using CSS Grid, to allow our data to be organized in an easy to read way and to look good! We're also making use of some pre-existing colors variables that are used within the project to keep the color use consistent.

Once you save those styles and reload the page, it should look much better:

Adding case statistics to the dashboard

From here, feel free to add more stats or adjust them to your liking. In the demo I created, I added the stats for active cases, critical cases, and recovered cases. If you'd like to do the same, you can check out the commit.

Follow along with the commit!

Step 3: Make the data human friendly

Now the rest of this walkthrough could be considered optional, but ultimately we want people to be able to read these statistics, right? So let's make the numbers a little more easy to read.

First, let's open our src/lib/util.js file and add this function:

/**
 * commafy
 * @description Applies appropriate commas to large numbers
 */

export function commafy(value) {
  let numberString = `${value}`;

  numberString = numberString.split('');

  numberString.reverse();

  numberString = numberString.reduce((prev, current, index) => {
    const shouldComma = (index + 1) % 3 === 0 && index + 1 < numberString.length;
    let updatedValue = `${prev}${current}`;
    if ( shouldComma ) {
      updatedValue = `${updatedValue},`;
    }
    return updatedValue;
  }, '');

  numberString = numberString.split('');
  numberString.reverse()
  numberString = numberString.join('');

  return numberString;
}

This function will take a number and turn it into a string with commas. To walk through what it does:

• Takes in a value as an argument. For our use, this value will most likely be a number.
• It converts the value into a string. We'll use this to work with adding commas to our number.
• We split that string into an array and reverse it. We want to reverse it because it makes it easier to add our commas depending on the index.
• We use the javascript reduce function to recreate our number-string. After every 3 numbers, we want to add a comma.
• Once we have our new value with the commas, we want to re-reverse it. So we split it again, reverse the array of characters, and re-join it, which is what we return

And now that we have our commafy function, let's use it. Back inside src/pages/index.js, let's import our function at the top of the page:

import { commafy } from 'lib/util';

Then, in our dashboardStats array, let's replace every number value with a ternary expression and function that will convert our number if it's available:

value: stats ? commafy(stats?.cases) : '-'

This line checks to see if stats exists. If it does, we commafy the cases value. If it doesn't exist, we return a - to show it's unavailable.

Once we repeat that process for all of our numbers, we can save, reload the page, and see our human friendly numbers!

Formatting the statistics to be human readable

Follow along with the commit!

Step 4: Add the Last Updated date

Finally, we want to make sure people are staying informed and understand the last time this data was updated. Luckily, our API provides a Last Updated date for us, so let's use it!

At the bottom of our "tracker" div under tracker-stats, let's add the following:

<div className="tracker-last-updated">
  <p>
    Last Updated: { stats?.updated }
  </p>
</div>

This creates a new section where we simply include the updated property from our stats. And if we save and reload the page, we can see the last updated date!

Adding last updated to the dashboard

But how could we even understand what that number is, unless you're the computer crawling this blog post? So let's change it to a human readable format like we did with our numbers.

Inside of our src/lib/util.js file, let's add another function:

/**
 * friendlyDate
 * @description Takes in a date value and returns a friendly version
 */

export function friendlyDate(value) {
  const date = new Date(value);
  return new Intl.DateTimeFormat('en', {
    year: 'numeric',
    month: 'short',
    day: '2-digit',
    hour: 'numeric',
    minute: 'numeric'
  }).format(date);
}

This function creates a new Date object, then uses the javascript International DateTimeFormat API to convert it into a friendly readable format!

Once that's saved, let's import it next to our commafy function at the top of src/pages/index.js:

import { commafy, friendlyDate } from 'lib/util';

Then we can update our code similar to how we updated our numbers:

Last Updated: { stats ? friendlyDate(stats?.updated) : '-' }

And if we save and reload, we see it in a human readable way!

Formatting the last updated date

Finally for our "last updated" should look like it fits in with the rest of the dashboard, so let's add a few more styles. Inside of our _tracker.scss file we were working with earlier:

.tracker-last-updated {

  color: white;
  background-color: $blue-grey-900;
  padding: .8em 0;

  p {
    color: $blue-grey-300;
    font-size: .8em;
    text-align: center;
    margin: 0;
  }

}

And once we hit save and refresh the browser, we have our dashboard statistics with the last updated time! ?

Final dashboard with formatted lasted updated date

Follow along with the commit!

What can I do next?

Make the marker tooltip data human friendly

Now that we have our handy commafy and friendlyDate functions, we can reuse those functions to clean up the data in our country marker popups!

Use the fetchTracker function to poll for updates

Inside of the useTracker hook we created, we exported a function called fetchTracker. This allows us to force a request to the API to fetch new data. To make sure our map stays current even when somebody doesn't refresh the page, we can create a timer in javascript to regularly invoke that function to update our dashboard data.

Clear the map layers before re-adding the new ones

One thing we're currently not doing is cleaning up old layers before adding a new one. The way the map is set up, it just keeps layering them on top. What we can do is before we add all of our new layers, we can clear out the old ones. Check out this commit to get started!

Want to learn more about maps?

You can check out a few of my other resources to get started:

• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet (Part 1 of this post)
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

• What are we going to build?
• What is Mapbox?
• Part 1: Creating a custom Mapbox style
• Part 2: Adding a custom TileLayer to React Leaflet
• Part 3: Adding a custom basemap to Gatsby Starter Leaflet
• Securing your Mapbox key
• Want to learn more about maps?

What are we going to build?

We’re going to walk through creating a new basic Mapbox style in our Mapbox account. Once created, we’re going to use their Map API to add a custom basemap to our React Leaflet app.

Gatsby Starter Leaflet with Mapbox basemap

For our map, we’re going to use this Leaflet Gatsby Starter I created that will allow you to easily spin up a new mapping app. Before we spin that up though, I’ll walk you through how to add it using only React Leaflet components.

A mapping app?

Yup! Maps are used all around the world to study datasets for geographic locations. They're important tools for scientists and others that are trying to help the world.

Coronavirus (COVID-19) custom map

If you want to learn more about building a map and adding data to it, you can check out some of my other articles first such as creating a Coronavirus (COVID-19) map or a Summer Road Trip map as well as a little bit of inspiration about why Anyone Can Map.

What is Mapbox?

Mapbox is a mapping platform that allows its customers to create custom mapping solutions. They also leverage a variety of APIs that provide powerful capabilities for building map features.

mapbox.com

For our purposes, we’re going to utilize their Map API, specifically their Static Tiles API, to serve a custom map style that we create.

Part 1: Creating a custom Mapbox style

To get the look and feel that we want for our map, it’s important to have a basemap that helps make our data present itself without distractions. Plus, sometimes it’s fun to have a custom map.

Mapbox account

The first thing we’ll need to set up our custom Mapbox style is to have an account. I'm not going to walk you through that process, but you can head over to Mapbox’s website where you can sign up for free: mapbox.com

Creating a new custom style

Creating a new style in Mapbox isn’t as hard as it sounds. While it can get really complex if you want something unique, we can copy one of Mapbox’s default styles to get started.

First, head over to Mapbox’s Studio dashboard by clicking your account link in the top right corner when logged in.

Mapbox Studio

Once we’re on our Studio dashboard, we want to select the New Style button.

Create a new style in Mapbox Studio

After clicking the button, a modal will pop up allowing you to choose a template. You can choose whatever you want here, but I’m going to choose Monochrome with a variation of Dark. And after you’ve selected your template, click the Customize button.

Select and customize a template for a new style in Mapbox Studio

And now we’re dropped into our customization UI.

Mapbox customize style UI

From here, you can really do what you’d like. There are a ton of options to customize your map. It’s a little complex to try to dig in here, but Mapbox provides some resources to try to help you get productive.

Generating a Mapbox token

Once you’re happy with your new style and everything’s published, we want to generate a token that we’ll use for providing access to our Map.

Head on over to the Account section of the Mapbox dashboard.

Creating a new token in Mapbox

Mapbox provides you with a “default” token that you can use in your applications. You're free to use this, but I recommend creating a new token that you can provide a unique name, that way if you ever blow past the free tier of Mapbox, you’ll be able to track your usage.

Additionally, it’s best to keep a separate token for each application, that way you can easily rotate an individual key, without having to update every application using it.

Once you click Create a token, you can set up the key how you’d like, with the scopes and permissions you choose, but for our purposes, you can leave all of the Public scopes checked for our map, which they do by default.

Create a new access token in Mapbox

Configuring our custom endpoint

For this tutorial, we’re going to use Mapbox’s Static Tiles service.

Mapbox Static Tiles Maps API

Our endpoint will look like the following:

https://api.mapbox.com/styles/v1/{username}/{style_id}/tiles/256/{z}/{x}/{y}@2x?access_token={access_token}

There are a few parameters here we need to understand:

• username: this will be your Mapbox account’s username
• style_id: this will be the ID of the style you created before
• z, x, y: these are parameters that Leaflet programmatically swaps out, so we want to leave them as is
• access_token: this is the Mapbox key you created above

To find your username and style ID, we can use the Style URL for our new Mapbox style to get those values.

Finding the Style URL in Mapbox Studio

In my example, my Style URL looks like:

mapbox://styles/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p

colbyfayock is my username and ck8lryjfq0jdo1ip9ctmuhc6p is my style ID.

And once I update my endpoint parameters, the final tilepoint URL will look like:

https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN

Part 2: Adding a custom TileLayer to React Leaflet

When building a map with React Leaflet, your main component will be a <Map> that wraps the entirety of the app. This is what sets up your Map instance for Leaflet.

For our purposes here, we’re going to use the example on the React Leaflet homepage as our starting point.

React Leaflet TileLayer Component

Inside of your <Map> component you include a <TileLayer> component, which defines the imagery of the world that you base your map upon.

The example on the React Leaflet homepage uses a public version of OpenStreetMap as their TileLayer, which is an open source map project created and updated by people all around the world.

<Map center={position} zoom={13}>
  <TileLayer
    url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
    attribution="&copy; <a href=&quot;http://osm.org/copyright&quot;>OpenStreetMap</a> contributors"
  />
</Map>

This gives you a basic map, but we want to swap in Mapbox so we can set up a custom look and feel for our map.

Custom Mapbox TileLayer

To add our custom style, we’ll want to update the url and attribution props of the TileLayer component.

For URL, it will simply be the custom style endpoint we created earlier, so in my example, it looks like:

https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN

For attribution, we want to credit Mapbox as the service, so we want to set our attribution as:

Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/2.0/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>

When plugged in to our TileLayer, our code should now look like this:

<Map center={position} zoom={13}>
  <TileLayer
    url="https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN"
    attribution="Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/2.0/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>"
  />
</Map>

And once we open up our map, we should see our new basemap!

React Leaflet with a Mapbox basemap

See the code!

If you want to see how I did it, check out the diff commit by commit.

The only caveat there is I created an .env.development.local file in the root of my project in which I stored a new environment variable called REACT_APP_MAPBOX_KEY to store my Mapbox key.

Part 3: Adding a custom basemap to Gatsby Starter Leaflet

I’ve written a few other articles on how to get started with my Leaflet Gatsby Starter, but for this part, we’ll want to have a basic app spun up that we can use to change our TileLayer endpoint.

Setting up our React Leaflet Gatsby app

To get started, check out the instructions on the Starter github:

https://github.com/colbyfayock/gatsby-starter-leaflet

Once you’re ready, you should have a basic mapping app ready to go!

New Leaflet Gatsby app in the browser

Configuring our Mapbox service

The first thing we’ll want to do is add Mapbox as a service in our src/data/map-services.js file.

Taking our custom endpoint URL that we created in Part 1, let’s set up a new object with a name of Mapbox, and with a url and attribution similar to what we did in Part 2.

export const mapServices = [
  {
    name: ‘OpenStreetMap’,
    attribution: '&copy; <a href="http://osm.org/copyright”>OpenStreetMap</a> contributors’,
    url: ‘https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png’
  },
  {
    name: ‘Mapbox’,
    attribution: ‘Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/2.0/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>’,
    url: `https://api.mapbox.com/styles/v1/colbyfayock/ck8c2foj72lqk1jnug0g2haw0/tiles/256/{z}/{x}/{y}@2x?access_token=MY_ACCESS_TOKEN`
  }
];

Using our Mapbox map service

Once you have your Mapbox service set up, all that’s left is to open up the src/pages/index.js file, find the mapSettings object definition, and update the defaultBaseMap property to Mapbox.

const mapSettings = {
  center: CENTER,
  defaultBaseMap: ‘Mapbox’,
  zoom: DEFAULT_ZOOM,
  mapEffect
};

Save that change, refresh the map in your browser, and you should now see your custom basemap style!

Gatsby Starter Leaflet with custom Mapbox basemap in browser

See the code!

If you want to see how I did it, check out the diff with the commit.

The only caveat there is I created an .env.development file in the root of my project in which I stored a new environment variable called GATSBY_MAPBOX_KEY to store my Mapbox key.

Securing your Mapbox key

Environment variables

Part of most development processes that use individual keys will generally set the keys up as environment variables. Environment variables are configured settings that don’t live in the code itself.

This is important because it prevents your key from being checked in to your code, which is bad from a security perspective, but it also allows you to provide a different key for different environments.

When generating your keys, try to keep this in mind, as it can save you in the long run.

Locking down your Mapbox key

In your settings when creating a token or when editing a token, Mapbox allows you to specify only the URLs you want your key to be accessible from.

Though Mapbox has a generous free tier, you probably want to keep it locked down only to the URLs that you’re using it on. You can create multiple keys, where one could be for public use on your website and one would be for your local development.

This is helpful for instance, where you have a key that will never be used publicly for development purposes, but then you have a key that you deploy with, which can be locked down only to that URL.

If someone grabs your key, they could plug it into their own website and use up all of your free tier, potentially running up your bill!

Want to learn more about maps?

You can check out a few of my other resources to get started:

• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet
• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

Update: The original NovelCOVID API v1 endpoint has been deprecated. Please update and use the following instead: https://corona.lmao.ninja/v2/countries

Author’s Note: This is meant to be a demo and proof of concept for putting together an impactful mapping application using real life data. For complete and accurate analysis, please make sure to use tools like Johns Hopkins University dashboard. Stay home and be safe! ❤️

• What are we going to build?
• What do we need before we get started?
• Step 1: Cleaning up some unneeded code
• Step 2: Fetching the Coronavirus data
• Step 3: Transform the Coronavirus data into a geographic data format
• Step 4: Adding the Coronavirus data to the map
• What else can we do?
• Be safe and stay informed
• Want to learn more about maps?

What are we going to build?

We’ll be putting together a mapping application that uses an API containing recent Coronavirus statistics and maps out the locations and impact each country is facing.

Coronavirus map dashboard demo

On the map, we’ll show a marker for each country with the number of confirmed cases. On top of that, we’ll include a little popup tooltip that shows more in depth information.

The map we’ll build will mostly look like the above, but will look a little simpler. We’ll utilize the OpenStreetMap public tileserver instead of using a custom Mapbox

To get started, we’re going to use this Leaflet Gatsby Starter I created to make the initial setup a little smoother. With our app bootstrapped, we’ll fetch our data and add markers to the map with our data.

Woah, a mapping app?

Yup. If you haven’t played with maps before, don’t be discouraged! It's not as bad as you probably think. If you’d rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

If you followed along with my previous tutorials for building a Santa Tracker or creating a Summer Road Trip map, you can follow the same steps to get started. If not, we’ll want to make sure we have the following set up:

• node or yarn - I'll be using yarn, but you can substitute with npm where appropriate
• Gatsby’s CLI - yarn global add gatsby-cli

If you’re not sure about one of the above, you can try checking out the beginning my previous tutorial.

We’ll also want to set up a foundation for our map. We can do this by utilizing the Leaflet Gatsby Starter I put together that provides us a basic setup with Leaflet and React Leaflet.

gatsby new my-coronavirus-map https://github.com/colbyfayock/gatsby-starter-leaflet

Creating a new Leaflet Gatsby app in the terminal

After that’s finished running, you can navigate to the newly created project directory and start your local development server:

cd my-coronavirus-map
yarn develop

Starting your Gatsby app in the terminal

If all goes as planned, your server should start and you should now be able to see your basic mapping app in your browser!

New Leaflet Gatsby app in the browser

Follow along with the commit!

Step 1: Cleaning up some unneeded code

The Gatsby Starter we're using to spin up this app comes with some demo code that we don’t need here. We’ll want to make all of the changes below in the file src/pages/index.js, which is the homepage of our app.

First, let’s remove everything from the mapEffect function. This function is used to run code that fires when the map renders.

// In src/pages/index.js
async function mapEffect({ leafletElement } = {}) {
  // Get rid of everything in here
}

We’ll also change the variable name of our leafletElement simply for being able to more easily understand the code as we write it.

async function mapEffect({ leafletElement: map } = {}) {
}

Next, we don’t want a marker this time, so let’s remove the <Marker component from our <Map component:

<Map {...mapSettings} />

Now that we have those pieces cleared out, we can remove all of the following imports and variables from the top of our file:

• useRef
• Marker
• promiseToFlyTo
• getCurrentLocation
• gatsby_astronaut
• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• ZOOM
• popupContentHello
• popupContentGatsby
• markerRef

After, our map should still work, but not do anything.

New mapping app with nothing going on

Follow along with the commit!

Step 2: Fetching the Coronavirus data

For our app, we’re going to use the NovelCOVID API. Particularly, we’re going to use the countries endpoint to fetch the list of our countries and the stats associated with them.

For making requests, I personally like to use axios as it has a nice to use API. If you want to use fetch or your own favorite request library, substitute that in for this step.

We’ll start by installing axios:

yarn add axios

Once that installs, remember to restart your server.

Import the axios package ta the top of our pages/index.js file:

import axios from 'axios';

Next we’ll actually make our request. Inside our mapEffect function, let’s try to make a request to the API endpoint:

async function mapEffect({ leafletElement: map } = {}) {
    let response;

    try {
      response = await axios.get('https://corona.lmao.ninja/v2/countries');
    } catch(e) {
      console.log(`Failed to fetch countries: ${e.message}`, e);
      return;
    }

    const { data = [] } = response;
}

In this snippet, we’re doing the following:

• Setting up a response variable that will allow us to store the response
• Adding a try/catch block that will catch any API errors if the request fails
• If the request is successful, we store the response in the response variable
• If the request fails, we console log out the error and return out of the function so we don’t continue to run the code with a failed request
• Once we have our response, we can destructure data from the response and set the default value to an empty array, as that will be the type of data we need

After that’s set up, we can console log out the data object and we’ll see our data successfully fetched!

Logging the Coronavirus location data to the browser console

Follow along with the commit!

Update: The previous commit includes a link to the original NovelCOVID v1 API endpoint which has now been deprecated. Please use this instead: https://corona.lmao.ninja/v2/countries.

See updated commit.

Step 3: Transform the Coronavirus data into a geographic data format

Now that we have our data, we can transform it into a geographic data format, particularly GeoJSON, that will allow us to interface with Leaflet.

Let’s start by adding this block of code:

const { data = [] } = response;
const hasData = Array.isArray(data) && data.length > 0;

if ( !hasData ) return;

const geoJson = {
  type: 'FeatureCollection',
  features: data.map((country = {}) => {
    const { countryInfo = {} } = country;
    const { lat, long: lng } = countryInfo;
    return {
      type: 'Feature',
      properties: {
       ...country,
      },
      geometry: {
        type: 'Point',
        coordinates: [ lng, lat ]
      }
    }
  })
}

So what are we doing here?

• We create a new constant called hasData that checks if our data variable is an array and has data
• If we don’t have data, we want to return out of the function, as we don’t want to try to add data we don’t have
• We create a geoJson object that will be our GeoJSON document
• Our document is of type FeatureCollection and as our features we loop through our dataset
• For each country in our data, we obtain the lat and lng to create a point for our map
• We additionally add our country data as properties so we can access it within our mapping APIs

If you console.log this object our into your browser and copy the contents, you can paste this into geojson.io and see the location data show up correctly.

Previewing Coronavirus location data on geojson.io

With this GeoJSON document, we'll now be able to add it to our map.

Follow along with the commit!

Step 4: Adding the Coronavirus data to the map

We have our GeoJSON document with our location data, so let’s add it to the map.

Let’s start with this code block. It's a long one, but we’ll break it down piece by piece:

const geoJsonLayers = new L.GeoJSON(geoJson, {
  pointToLayer: (feature = {}, latlng) => {
    const { properties = {} } = feature;
    let updatedFormatted;
    let casesString;

    const {
      country,
      updated,
      cases,
      deaths,
      recovered
    } = properties

    casesString = `${cases}`;

    if ( cases > 1000 ) {
      casesString = `${casesString.slice(0, -3)}k+`
    }

    if ( updated ) {
      updatedFormatted = new Date(updated).toLocaleString();
    }

    const html = `
      <span class="icon-marker">
        <span class="icon-marker-tooltip">
          <h2>${country}</h2>
          <ul>
            <li><strong>Confirmed:</strong> ${cases}</li>
            <li><strong>Deaths:</strong> ${deaths}</li>
            <li><strong>Recovered:</strong> ${recovered}</li>
            <li><strong>Last Update:</strong> ${updatedFormatted}</li>
          </ul>
        </span>
        ${ casesString }
      </span>
    `;

    return L.marker( latlng, {
      icon: L.divIcon({
        className: 'icon',
        html
      }),
      riseOnHover: true
    });
  }
});

So what are we doing here?

• We create a new instance of L.GeoJSON which will transform our GeoJSON document into something Leaflet will understand
• Inside that instance, we define a custom pointToLayer function. This allows us to customize the map layer Leaflet creates for our map
• In our function, we assign and create our datapoints that we want. Most of it is destructuring, but we format the cases count to show 1k+ instead of 1000 and a formatted date instead of the timestamp
• We create an HTML string block which is used to define our map marker that will be added to the map. This also includes the HTML for the tooltip that will pop up when hovering over a marker
• We return L.marker with our custom configuration that includes a class of icon for the container and our custom HTML.
• Additionally, we add the riseOnHover property so when hoving over a marker, it surfaces itself above over the other markers on the map

We also want to add a bit of CSS here so that we can make sure our markers show up in the map and are usable. Let’s add this snippet to our assets/stylesheets/components/_map.scss file:

.icon-marker {

  display: flex;
  position: relative;
  justify-content: center;
  align-items: center;
  color: white;
  width: 3.6em;
  height: 3.6em;
  font-size: .7em;
  font-weight: bold;
  background-color: $red-800;
  border-radius: 100%;
  box-shadow: 0 2px 5px rgba(black, .9);

  &:hover {

    .icon-marker-tooltip {
      display: block;
    }

  }

}

.icon-marker-tooltip {

  display: none;
  position: absolute;
  bottom: 100%;
  width: 16em;
  font-size: 1.4em;
  padding: 1em;
  background-color: $blue-grey-900;
  border-radius: .4em;
  margin-bottom: 1em;
  box-shadow: 0 3px 5px rgba(black, .9);

  &:before {
    display: block;
    position: absolute;
    bottom: -.6em;
    left: 50%;
    content: '';
    width: 1.4em;
    height: 1.4em;
    background-color: $blue-grey-900;
    transform: rotate(45deg);
    margin-left: -.7em;
  }

  h2 {
    font-size: 1.5em;
    line-height: 1.2;
    margin-bottom: .1em;
    margin-top: 0;
  }

  h3 {
    font-size: 1.2em;
    margin: .1em 0;
    font-weight: normal;
    color: $blue-grey-100;
  }

  ul,
  p {
    font-weight: normal;
  }

  ul {
    list-style: none;
    padding: 0;
    margin: .6em 0 0;
  }

}

What we’re doing:

• We create our round markers using the .icon-marker class and set up our .icon-marker-tooltip class to show up when hovered over
• Our .icon-marker-tooltip class is hidden by default, as it’s our tooltip, but we position it absolutely to appear over top of our marker and formatted the way we want it

And finally, once we have our geoJsonLayers created with our styling added, we can add it to the map!

geoJsonLayers.addTo(map)

Map with Coronavirus location data

Now you might be wondering why it doesn't appear to be centering properly. Go ahead and change the LOCATION variable at the top of the index.js file to:

const LOCATION = {
  lat: 0,
  lng: 0
};

Once that’s set, when the page reloads, the map should be centered in the middle of the world!

Map with Coronavirus location data centered with a tooltip

Follow along with the commit!

Yay, we did it! ?

If you followed along, you now have created your own Coronavirus map dashboard that gives some quick stats about the cases around the world.

Take what you learned and run with it. You can apply this to any other type of data that you can imagine.

What else can we do?

Add more styles and a custom basemap

In my original demo, I set up a custom basemap using Mapbox that allows me to have a dark background making the markers easier to see.

Creating a new basemap in Mapbox Studio

Mapbox is great and has a nice free tier if you’re interested in getting started.

Once you have a Mapbox account, you can even copy the style I used and make it your own.

Basic Dark Mapbox Theme

To learn how to integrate it, you can try to check out the source code of my original demo:

https://github.com/colbyfayock/coronavirus-map-dashboard

Add overview dashboard stats

Dashboards with maps like the Johns Hopkins University app allows us to see more than a look on the map, but a glimpse at quick stats about the cases around the world.

Johns Hopkins University Coronavirus Map Dashboard - March 29, 2020

The NovelCOVID API has more endpoints like /all that provide a few global stats.

Be safe and stay informed

I want to reiterate that you should make sure you're staying up to date using official sources for information, such as the Johns Hopkins University dashboard. Though the data should be reliable, it should also be considered a proof of concept for building a map and referencing, but shouldn't be considered for any kind of statistical analysis.

Please take care of yourself during these times. We're all in this together! ❤️

Want to learn more about maps?

You can check out a few of my other resources to get started:

• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

• What are we going to build?
• What do we need before we get started?
• Step 1: Cleaning up some unneeded code
• Step 2: Create our road trip locations
• Step 3: Prepare our app with some functions
• Step 4: Building our trip path
• Step 5: Styling our map components
• Want to learn more about maps?

Author’s Note: Even though we’re going through some challenging times, we can still be optimistic that we’ll get through this together and be able to enjoy our summer. Stay safe and wash your hands. ❤️

What are we going to build?

We’ll be walking through building a new mapping app that shows a route representing the trip. Each location will have a little card where we can add a picture and some things we did.

Colbana's Summer Road Trip

To get started, we’re going to use this Leaflet Gatsby Starter I created to make the initial setup a little smoother. With our app bootstrapped, we’ll create our list of locations and use Leaflet’s API to draw our route on the map.

Woah, a mapping app?

Yup. If you haven’t played with maps before, don’t be discouraged! It's not as bad as you probably think. If you’d rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

If you followed along with my last tutorial for building a Santa Tracker, you can follow the same steps to get started. If not, we’ll want to make sure we have the following set up:

• node or yarn - I'll be using yarn, but you can substitute with npm where appropriate
• Gatsby’s CLI - yarn global add gatsby-cli

If you’re not sure about one of the above items, you can try checking out the beginning of my previous tutorial.

We’ll also want to set up a foundation for our map. We can do this by utilizing the Leaflet Gatsby Starter I put together that provides us a basic setup with Leaflet and React Leaflet.

gatsby new my-road-trip https://github.com/colbyfayock/gatsby-starter-leaflet

Creating a new Leaflet Gatsby app in the terminal

After that’s finished running, you can navigate to the newly created project directory and start your local development server:

cd my-road-trip
yarn develop

Starting your Gatsby app in the terminal

If all goes as planned, your server should start and you should now be able to see your basic mapping app in your browser!

New Leaflet Gatsby app in the browser

Step 1: Cleaning up some unneeded code

The Gatsby Starter we're using to spin up this app comes with some demo code that we don’t need here. We’ll want to make all of the changes below in the file src/pages/index.js, which is the homepage of our app.

First, let’s remove everything from the mapEffect function. This function is used to run code that fires when the map renders.

// In src/pages/index.js

async function mapEffect({ leafletElement } = {}) {
  // Get rid of everything in here
}

Next, we don’t want a marker this time, so let’s remove the <Marker component from our <Map component:

<Map {…mapSettings} />

Now that we have those pieces cleared out, we can remove all of the following imports and variables from the top of our file:

• useRef
• Marker
• promiseToFlyTo
• getCurrentLocation
• gatsby_astronaut
• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• ZOOM
• popupContentHello
• popupContentGatsby
• markerRef

After, our map should still work, but not do anything.

New mapping app with nothing going on

Follow along with the commit

Step 2: Create our road trip locations

This step will involve preparing our location data that will populate our road trip app. Our locations will include properties like a name, date, things we did, and a picture if we want.

First, create a new file in the src/data directory called locations.js. Inside of that file, we want to create and export a new array.

export const locations = [
  {
    placename: ‘Herndon, VA’,
    date: ‘August 1, 2015’,
    location: {
      lat: 38.958988,
      lng: -77.417320
    },
    todo: [
      ‘Where we start! ?’
    ]
  },
  {
    placename: ‘Middlesboro, KY',
    date: ‘August 1, 2015’,
    location: {
      lat: 36.627517,
      lng: -83.621635
    },
    todo: [
      ‘Cumberland Gap ?’
    ]
  }
];

You can use the above to get started, but you’ll eventually want to change the details to something of your choosing.

If you want to add an image to your location, you can do so by including an image property to the object. You can use either a URL string or you can import a local file if you have one available, like I’m doing in this example:

import imgHerndonStart from 'assets/images/herndon-start.jpg’;

export const locations = [
  {
    placename: ‘Herndon, VA’,
    date: ‘August 1, 2015’,
    image: imgHerndonStart,
    location: {
      lat: 38.958988,
      lng: -77.417320
    },
    todo: [
      ‘Where we start! ?’
    ]
  }
]

Once we have that file created, we can now import our locations into our src/pages/index.js file so we can use it in our next step:

import { locations } from 'data/locations’;

If you add a console.log(locations) inside of your page, you should now see all of your location data in an array!

Follow along with the commit

Step 3: Prepare our app with some functions

To try to keep things simple and focused, I grouped together 3 important components of creating our map into functions. Though it’s available to copy and paste, we’ll walk through what’s happening in each function.

You can place each of these functions at the bottom of the src/pages/index.js file so they’re ready to use in our next step.

createTripPointsGeoJson

Our first function is going to take the array of our locations and return a GeoJSON document, with our locations mapped into an individual Feature. We’ll use this function to create the individual points on our map.

What is a GeoJSON document? It's essentially a JavaScript object or JSON document with a specific structure that creates consistency with geographical data.

function createTripPointsGeoJson({ locations } = {}) {
  return {
    “type”: “FeatureCollection”,
    “features”: locations.map(({ placename, location = {}, image, date, todo = [] } = {}) => {
      const { lat, lng } = location;
      return {
        “type”: “Feature”,
        “properties”: {
          placename,
          todo,
          date,
          image
        },
        “geometry”: {
          “type”: “Point”,
          “coordinates”: [ lng, lat ]
        }
      }
    })
  }
}

So what’s happening in the above?

• We take an argument of locations, which will be our array of destinations
• We return an object with some dynamic properties associated with it
• Within the object, we map our locations to individual Feature objects
• Each object includes a Point shape using our coordinates
• It additionally includes our properties that store our metadata

When this function is invoked, we will have a newly created JavaScript object that includes an array of Points representing the locations we are stopping at on our road trip.

createTripLinesGeoJson

We’re going to create another function that’s similar to the previous one. This time however, instead of points, we want to create lines that represent going from one point to the next.

function createTripLinesGeoJson({ locations } = {}) {
  return {
    “type”: “FeatureCollection”,
    “features”: locations.map((stop = {}, index) => {
      const prevStop = locations[index - 1];

      if ( !prevStop ) return [];

      const { placename, location = {}, date, todo = [] } = stop;
      const { lat, lng } = location;
      const properties = {
        placename,
        todo,
        date
      };

      const { location: prevLocation = {} } = prevStop;
      const { lat: prevLat, lng: prevLng } = prevLocation;

      return {
        type: ‘Feature’,
        properties,
        geometry: {
          type: ‘LineString’,
          coordinates: [
            [ prevLng, prevLat ],
            [ lng, lat ]
          ]
        }
      }
    })
  }
}

So you’ll immediately notice that this is very similar to our last function. We’re returning an object and setting our metadata properties on a list of Features.

The big difference, however, is that we're creating a Line. To do this, we're looking up and referring to prevStop which will be the previous stop. We’ll use both the previous stop and our current stop in order to have 2 points which we can use to draw the line.

If we don’t have a previous stop, we return an empty array, which basically means we’re at the beginning of our journey with no line before it.

With the previous stop and current stop, we create a LineString type of Feature with our 2 points.

tripStopPointToLayer

Our last function is going to allow us to create custom content for each of the points that we will be adding to our map. We’ll actually be utilizing this function within a Leaflet property, so we’ll be conforming our arguments to that specification.

function tripStopPointToLayer( feature = {}, latlng ) {
  const { properties = {} } = feature;
  const { placename, todo = [], image, date } = properties;

  const list = todo.map(what => `<li>${ what }</li>`);
  let listString = ‘’;
  let imageString = ‘’;

  if ( Array.isArray(list) && list.length > 0 ) {
    listString = list.join(‘’);
    listString = `
      <p>Things we will or have done…</p>
      <ul>${listString}</ul>
    `
  }

  if ( image ) {
    imageString = `
      <span class=“trip-stop-image” style=“background-image: url(${image})”>${placename}</span>
    `;
  }

  const text = `
    <div class=“trip-stop”>
      ${ imageString }
      <div class=“trip-stop-content”>
        <h2>${placename}</h2>
        <p class=“trip-stop-date”>${date}</p>
        ${ listString }
      </div>
    </div>
  `;

  const popup = L.popup({
    maxWidth: 400
  }).setContent(text);

  const layer = L.marker( latlng, {
    icon: L.divIcon({
      className: ‘icon’,
      html: `<span class=“icon-trip-stop”></span>`,
      iconSize: 20
    }),
    riseOnHover: true
  }).bindPopup(popup);

  return layer;
}

One thing you’ll notice as we work through this function is that we create strings of HTML text. Given that the Leaflet API we’re utilizing for this doesn’t interface directly with React, we have to build out HTML manually to pass it in to our functions.

Starting from the top:

• We take in 2 arguments, feature and latlng. Leaflet passes these 2 values in for us to use in our function.
• We destructure our feature, allowing us to assign our metadata into variables
• 2 string variables are initialized that we’ll use for our HTML
• If we include a todo property as an array, we add a new list with each item inside.
• If we include an image, we create an image tag.
• With our newly created HTML strings, we construct the entirety of what will be our popup card for each strop
• With our popup HTML, we create a Leaflet popup instance
• With the latlng argument and our popup, we create a new Leaflet marker instance. This will represent the point on the map.
• Inside of the Marker creation, we create a basic HTML tag that well use to style the marker
• We then bind our popup to this new Marker instance. This will allow the popup to be associated with that individual Marker
• Finally, we return our newly created layer

Remember to make sure you put all of the functions above at the bottom of your src/pages/index.js page.

Once all of those functions are added, our map should still be the same thing, basically nothing happening.

Follow along with the commit

Step 4: Building our trip path

This is where things get interesting. We’ll now utilize the functions we created to build our road trip path. All of our work here will be within the mapEffect function inside of the src/pages/index.js file.

For context, our mapEffect function includes an argument called leafletElement. This value refers to the Map instance that Leaflet recognizes. This Map instance includes our map state as well as many utility functions to work with our map.

First, at the top of the function, we want to make sure we have a map. If not, we can return to bail out of the function.

if ( !leafletElement ) return;

Next, we want to use the eachLayer utility function and remove each layer from our map element. We do this to make sure we always have the correct map layer state.

leafletElement.eachLayer((layer) => leafletElement.removeLayer(layer));

With our cleaned up map, we can utilize 2 of the functions we created to create new GeoJSON objects.

const tripPoints = createTripPointsGeoJson({ locations });
const tripLines = createTripLinesGeoJson({ locations });

With our GeoJSON objects, we need to convert those to Leaflet GeoJSON instances, which we’ll use to add to the map.

const tripPointsGeoJsonLayers = new L.geoJson(tripPoints, {
  pointToLayer: tripStopPointToLayer
});

const tripLinesGeoJsonLayers = new L.geoJson(tripLines);

If you notice in the above, we're using our tripStopPointToLayer function. As I alluded to before, the geoJson instance we’re creating includes a property that allows us to pass in a function, giving us the ability to manipulate the layer creation. This is how we create our point and popup content.

We can proceed to adding both of those new layers to our map using the addTo .

tripPointsGeoJsonLayers.addTo(leafletElement);
tripLinesGeoJsonLayers.addTo(leafletElement);

Next, to make sure we zoom and center on the right location, we want to grab the bounds of the map using the getBounds function on our GeoJSON layer instance.

const bounds = tripPointsGeoJsonLayers.getBounds();

Finally, we fit our map's view to those bounds using the fitBounds function on our Map instance.

leafletElement.fitBounds(bounds);

Once you save and reload the page, you should now see a blue path representing the jump from each of our locations on the map!

Mapping app with road trip path

One issue though. If you notice, we only see the path. This is because we need to add some CSS which we’ll get to in the next step.

Follow along with the commit

Step 5: Styling our map components

Our last step will be adding some styles that will allow our markers to show and our popups to look just right.

In this step, we’ll be working inside of the _home.scss file, which you can find in src/assets/stylesheets/pages.

We can get started by copy and pasting this block of styles into the bottom of that file. With that done, we can walk through what’s happening.

.trip-stop {

  width: 400px;
  overflow: hidden;

  h2 {
    font-size: 1.4em;
    margin-top: 0;
    margin-bottom: .2em;
  }

  p,
  ul,
  h3 {
    font-size: 1.2em;
    font-weight: normal;
  }

  p {
    margin: .2em 0;
  }

  .trip-stop-date {
    color: $grey-600;
    font-size: 1em;
  }

  ul {
    padding: 0 0 0 1.4em;
    margin: 0;
  }

}

.trip-stop-image {
  display: block;
  float: left;
  overflow: hidden;
  width: 150px;
  height: 150px;
  text-indent: 100%;
  color: transparent;
  background-position: center;
  background-size: cover;
}

.trip-stop-content {
  float: left;
  width: 250px;
  padding-left: 1em;
}

.icon-trip-stop {

  display: block;
  width: 1.5em;
  height: 1.5em;
  background-color: $orange-500;
  border-radius: 100%;
  box-shadow: 0 2px 5px rgba(0,0,0,.5);

  &:hover {
    background-color: $deep-orange-400;
  }

}

There’s three components to our styles above:

• .trip-stop-images: Inside of the marker popup, we optionally can include an image. These styles set the size, make the text transparent, (it’s there for accessibility), and float it to the left so that our popup content can align correctly side by side.
• .trip-stop-content: This refers to the other half of our popup content. All we need to do here is make sure our size is appropriate and that it floats next to our image.
• .icon-trip-stop: The HTML tag that we’re using as our icon designation gets styled here. We size it up, set a color using a predetermined Scss variable, and we’re good to go.

Once those styles are saved, you should now see the points on the map representing each location. Additionally, you should be able to click each of these points to open up a popup containing information about the stop.

Road trip mapping app with popups

Follow along with the commit

Optional Last Step: Style Tweaks

The last thing that's completely optional is to make a few style tweaks to give your site a little personality. I’m not going to go over this in details, but if you’d like to follow along and dress things up a little bit, you can follow along with this commit which shows each code change I made.

Final version of the road trip mapping app

Follow along with the commit

Yay, we did it!

If you followed along with me, or skipped right to the starter, you should now have a mapping app that you can use for your next road trip.

The good news is this project can apply to anything! Want to map out your favorite restaurants in Washington, DC? Add your locations and remove the lines. Want to create line drawings over the map? That's certainly an option.

Whatever it is, if you enjoyed getting this map spun up, get creative and apply it to your next project!

Want to learn more about maps?

You can check out a few of my other resources to get started:

• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• How to build a mapping app in React the easy way with Leaflet

Taking inspiration from a culinary great

If you’ve seen the Pixar movie Ratatouille, you should know who Chef Gusteau is. He helped our “little chef” Remy the rat navigate the culinary world and become the top chef of Paris.

Remy from Ratatouille overlooking Gusteau's in Paris

Throughout the movie, we get a lot of great quotes on their journey. But the one we're interested in here is Gusteau’s motto, and the title of his book, “Anyone can cook!” So how can we apply this and the lessons to our own mapping journey?

I’ll admit, part of the fun here was translating some of the lessons learned from one of my favorite movies, but there’s a lot to take in here. I'm going to walk through some examples and types of maps that should get you motivated to get started with your own mapping application. So let’s dive in!

Get inspired by learning about maps and the impact they have on the world

Food always comes to those who love to cook. - Chef Gusteau

Through my work, I’ve found it easy to fall in love with working on maps. Every day, scientists use maps to visualize data that can assist them in making more effective decisions. This directly translates to benefitting people all around the world and saving lives.

With this inspiration, you'll be taken on a journey to learn more about the different types of maps in this world and how they’re being used. You even might stumble upon some interesting data that explores your own neighborhood!

Active fires around the world

Take for instance NASA’s FIRMS service, which provides a realtime look at active fire data around the world.

Active fires around the world via NASA FIRMS

Fires are a real-world example of disasters that we can learn from. This tool is used to help manage resources for stopping and preventing those fires by allowing scientists and those that are curious to analyze burn areas and model the data itself.

Global cases of COVID-19

And something very current, cases of COVID-19 (Coronavrius) around the world by Johns Hopkins Center for Systems Science and Engineering.

Global cases of Coronavirus (COVID-19) from John Hopkins CSSE

This map tracks the spread of the virus in real time, allowing scientists to model it's coverage and produce study results to share with the global community.

Mapping tools like this provide an effective means of giving as much information as possible in a way that’s easy to understand to the people who can make a difference with the information.

Increased life expectancy

On a more positive note, we can get a detailed look over time of how life expectancy is improving around the world.

Life expectancy in 2019 from Our World in Data

While it’s increased more in some areas than others, the global improvements are clear, and we get to see this rise in some countries from hundreds of years ago!

Explore the beauty of maps and applying data to them

How can I describe it? Good food is like music you can taste, color you can smell. There is excellence all around you. You need only to be aware to stop and savor it. - Chef Gusteau

There’s also a creative side and beauty to great maps. Thick datasets applied to a map (or any medium) can often become literal works of art.

The Room of Change from Pentagram

Whether showcased in an exhibit or one of the many options to purchase on Etsy, presenting meaningful data in a beautiful way can be impactful not just from an informational perspective, but also a cultural one.

Sometimes the interactions can be fun

Maps can also provide some interactivity that makes them fun to explore while you learn more about the dataset, like this globe that maps out global commodities from DailyFX.

Global Commodities interactive map from DailyFX

Though the data can frequently be thick and boring on its own, that doesn’t mean we can't find more interesting ways to present the data to interact with.

And sometimes maps can provide a listening experience

This map from at radiooooo.com allows you to travel around the world and through time.

Music Radio from radiooooo.com

Their use of a map makes it easy to identify the part of the world the person wants to explore.

Stop and appreciate the maps around you

Whether you notice it or not when you’re browsing the web every day, you most likely run into visualizations of datasets that create powerful ways to present that data in a way that’s more easily understood.

_u/dancingchopstix's recordings of their truck driving travels_

Luckily, we don’t have to work hard to find this inspiration, as we can visit aggregations of beautiful maps and general datasets like that of /r/dataisbeautiful.

Experiment, be creative, explore other ways to visualize data

You must be imaginative, strong-hearted. You must try things that may not work, and you must not let anyone define your limits because of where you come from. Your only limit is your soul. - Chef Gusteau

Maps come in all shapes and sizes. While shaded geographic areas typically work well with election results, it might not work as well for showcasing your summer road trip.

50 State Project road trip map

Exploring common map types

You’ve probably experienced more map types than you realize. Given it’s a powerful way to present data, maps are used frequently across the web.

A choropleth map is commonly seen for election results and regional datasets where a particular geographic location represents a point of reference.

CNN Map of Democratic primary after Super Tuesday

Heat maps on the other hand allow you to reflect on the intensity of a data point over a given area. This is powerful when you want to represent both the area covered of a dataset but also range the data represents at the same time, such as population density.

ArcGIS GPW 2015 Population Density heat map from

Learn from others, but don’t be afraid to create a new path

Explore and play around with different techniques to visualize data on a map. There’s frequently not one way to do it, meaning you can be creative and experiment with different ways of presenting your map.

But that also means you don’t need to be stuck working within the constraints of the common map types. Use the tools available or create new ones and break new ground. The most important thing is presenting the data in a way that will provide the most impact to those consuming it.

Don’t give up, learn from your experiences

What I say is true — anyone can cook... but only the fearless can be great. - Chef Gusteau

While there may not always be a right way, there sometimes are wrong ways. But don’t let failure stop you!

Take these failures as a learning experience in your journey of creating interesting and effective maps. By being bold with your experimentation, you’ll find yourself discovering techniques or creating new ways that can ultimately help people better understand map data.

You don’t have to be a cartographer to build great maps

Not everyone can become a great artist; but a great artist can come from anywhere. - Anton Ego

Towards the end of Remy’s journey, the food critic Anton Ego who was once critical of Gusteau's claim that “anyone can cook” came to a realization of what our chef truly meant.

Ratatouille critic Anton Ego's revelation

While it’s not reasonable to assume that every single one of us will be a great mapper, everyone has the opportunity to try and explore the medium.

And it certainly helps that we have plenty of tooling to help us get there. Whether building your own with Leaflet or identifying a few locations on a Google Map, the resources and community around mapping are endless.

Jump in with some resources to get started

For the developers out there who are inspired to get started, here are a few resources to start off with mapping:

• How to build a mapping app in React the easy way with Leaflet
• How to Visualize Air Pollution using Folium Maps - An In Depth Tutorial
• How to integrate maps in React Native using react-native-maps
• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• How to Create your own Santa Tracker with Gatsby and React Leaflet
• Building Maps with Impact on React and the JAMstack (Video)
• Gatsby Starter Leaflet
• Leaflet
• OpenLayers
• My Maps by Google

What’s your favorite map experience or tool?

Share with me on Twitter!

The keys and values in the Map object can be any value (both objects and primitive values are valid).

Syntax

new Map([iterable])

Parameters

iterable An Array or other iterable object whose elements are key-value pairs.

Example

const myMap = new Map();
myMap.set('foo', 1);
myMap.set('bar', 2);
myMap.set('baz', 3);

myMap.get('foo');   // returns 1
myMap.get('baz');   // returns 3
myMap.get('hihi');  // return undefined

myMap.size;   // 3

console.log(myMap); // Map { 'foo' => 1, 'bar' => 2, 'baz' => 3 }

It's easy to create a new Map from existing 2D arrays of key-value pairs:

const myArr = [['foo', 1], ['bar', 2], ['baz', 3]];
const arrMap = new Map(myArr);

console.log(arrMap); // Map { 'foo' => 1, 'bar' => 2, 'baz' => 3 }

You can also convert an object into a Map with the help of the Object.entries:

const myObj = {
  foo: 1,
  bar: 2,
  baz: 3
}
const objMap = new Map(Object.entries(myObj));

console.log(objMap); // Map { 'foo' => 1, 'bar' => 2, 'baz' => 3 }

Map.prototype.get

Returns the value of the specified key from a Map object.

Syntax

myMap.get(key);

Parameters

key Required.

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);

myMap.get('foo');   // returns 1
myMap.get('baz');   // returns 3
myMap.get('hihi');  // return undefined

Map.prototype.set

Sets or updates an element with the specified key and value in a Map object. The set() method also returns the Map object.

Syntax

myMap.set(key, value);

Parameters

• key Required
• value Required

Example

const myMap = new Map();

// sets new elements
myMap.set('foo', 1);
myMap.set('bar', 2);
myMap.set('baz', 3);

// Updates an existing element
myMap.set('foo', 100);

myMap.get('foo');   // returns 100

Because set() returns the Map object it operated on, the method can be easily chained. For example, the code above can be simplified to:

const myMap = new Map();

// sets new elements
myMap.set('foo', 1)
  .set('bar', 2)
  .set('baz', 3)
  .set('foo', 100); // Updates an existing element

myMap.get('foo');   // returns 100

Map.prototype.size

Returns the number of elements in a Map object.

Syntax

myMap.size();

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);


myMap.size(); // 3

Map.prototype.keys

Returns a new Iterator object that contains the keys for each element in the Map object in insertion order.

Syntax

myMap.keys()

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);


const iterator = myMap.keys();

console.log(iterator.next().value); // 'foo'
console.log(iterator.next().value); // 'bar'
console.log(iterator.next().value); // 'baz'

Map.prototype.values

Returns an iterator object that contains the values for each element in the Map object in the order they were inserted.

Syntax

myMap.values()

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);


const iterator = myMap.values();
console.log(iterator.next().value); // 1
console.log(iterator.next().value); // 2
console.log(iterator.next().value); // 3

Map.prototype.delete

Removes the specified element from a Map object. Returns whether the key was found and successfully deleted.

Syntax

myMap.delete(key);

Parameters

key Required.

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);


myMap.size(); // 3
myMap.has('foo'); // true;

myMap.delete('foo');  // Returns true. Successfully removed.

myMap.size(); // 2
myMap.has('foo');    // Returns false. The "foo" element is no longer present.

Map.prototype.entries

Returns a new Iterator object that contains the [key, value] pairs for each element in the Map object in insertion order.

Syntax

myMap.entries()

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);


const iterator = myMap.entries();

console.log(iterator.next().value); // ['foo', 1]
console.log(iterator.next().value); // ['bar', 2]
console.log(iterator.next().value); // ['baz', 3]

Map.prototype.clear

Removes all elements from a Map object and returns undefined.

Syntax

myMap.clear();

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);


myMap.size(); // 3
myMap.has('foo'); // true;

myMap.clear(); 

myMap.size(); // 0
myMap.has('foo'); // false

Map.prototype.has

Given a Map with elements inside, the has() function allows you to determine whether or not an element exists inside the Map, based on a key that you pass.

The has() function returns a Boolean primitive (either true or false), which indicates that the Map contains the element or not.

You pass a key parameter to the has() function, which will be used to look for an element with that key inside the Map.

Example:

// A simple Map
const campers = new Map();

// add some elements to the map
// each element's key is 'camp' and a number
campers.set('camp1', 'Bernardo');
campers.set('camp2', 'Andrea');
campers.set('camp3', 'Miguel');

// Now I want to know if there's an element
// with 'camp4' key:
campers.has('camp4');
// output is `false`

The campers Map does not currently have an element with a 'camp4' key. Therefore, the has('camp4') function call will return false.

// If we add an element with the 'camp4' key to the map
campers.set('camp4', 'Ana');

// and try looking for that key again
campers.has('camp4');
// output is `true`

Since the map now does have an element with a 'camp4' key, the has('camp4') function call will return true this time!

In a more real-world scenario, you might not manually add the elements to the Map yourself, so the has() function would become really useful in those cases.

Map.prototype.forEach

Executes the passed function on each key-value pair in the Map object. Returns undefined.

Syntax

myMap.forEach(callback, thisArg)

Parameters

• callback Function to execute for each element.
• thisArg Value to use as this when executing callback.

Example

const myMap = new Map();
myMap.set('foo',1);
myMap.set('bar',2);
myMap.set('baz',3);

function valueLogger(value) {
  console.log(`${value}`);
}

myMap.forEach(valueLogger);
// 1
// 2
// 3

Buddy the Elf waving

To get in the spirit, we’re going to spin up a web app that includes a map that tracks Santa on it!

Edit 12/23: Updated the app to request directly to Santa's route, just in case the original API doesn't work as originally expected.

What are we going to build?

We’re going to work through building a mapping app that tracks Santa’s route and his current location.

To achieve this, we’re going to spin up a premade Gatsby starter that will give us a basic foundation for a map, utilize Google’s unofficial API to grab Santa’s route, and overlay his position and route on top of the map with Leaflet.

Woah, a mapping app?

Ay Caramba

Yup. If you haven’t played with maps before, don’t be discouraged! It's not as bad as you probably think. If you’d rather start with mapping basics, you can read more about how mapping works first.

What do we need before we get started?

For this exercise, I’m going to assume you have node or yarn installed. For each example, I'll use yarn, but use the tool of your choice.

You’ll also want to install Gatsby’s CLI globally which will allow us to use their Starter tools.

To set up Gatsby’s CLI, run the following command:

yarn global add gatsby-cli

After, you should be able to run gatsby -h to see the available commands, which means it’s successfully installed.

Running gatsby -h to verify install

For more info about the Gatsby CLI, you can check out their documentation.

Getting started with our map foundation

Once our command line tools are set up, the first thing we’ll want to do is create a new Gatsby project using a Leaflet starter I put together. It provides us with a basic setup with Leaflet and React Leaflet.

Starting in your project directory, let’s install the project:

gatsby new [directory] https://github.com/colbyfayock/gatsby-starter-leaflet

Make sure to replace [directory] with the location you want to set up your project.

Once you run that command, Gatsby will clone that project without any of the git references and install the packages required to start.

Installing Gatsby Starter Leaflet

To make sure it works, you can now navigate to that directory, spin up your server, and test it in the browser:

cd [directory]
yarn develop

Where you see [directory] above, make sure to use the same path as you did before when setting up the new Gatsby project.

Running Gatsby Starter Leaflet

If all goes as planned, your server should start and you should now be able to see your basic mapping app in your browser!

Gatsby Starter Leaflet in the browser

Cleaning things up

This starter comes with a quick example of how we can interact with the map. We're not going to need this at all for our purposes so we can go ahead and clean things up.

To start, we’re going to open up our index.js file, the homepage file, and get rid of everything inside of the mapEffect function, which leaves us with:

// In src/pages/index.js

async function mapEffect({ leafletElement } = {}) {
  // Get rid of everything in here
}

Now, let’s remove the Marker component nested inside of our Map, so we end up with:

<Map {…mapSettings} />

Now that we’re no longer using that functionality, we can get rid of the variables and references at the top of the file, so you can go ahead and remove:

• useRef
• promiseToFlyTo
• getCurrentLocation
• Marker
• gatsby_astronaut
• ZOOM
• timeToZoom
• timeToOpenPopupAfterZoom
• timeToUpdatePopupAfterZoom
• popupContentHello
• popupContentGatsby
• markerRef

Follow along with the commit.

Finding Santa

Now that we’re in a good place, let’s get our hands dirty and find Santa. To do this, we’re going to use Google’s unofficial, undocumented API. This means that it’s possible this API won’t be available the day after this get’s published, but let’s be optimistic.

Additionally, at the time of writing, it’s still showing last year’s destinations, so what we’re really going to be visualizing here is Santa’s previous year’s route, though the hope is this would reset on the 24th and we’ll all be merry!

Before we get Santa, let’s first add a line back to our mapEffect function:

async function mapEffect({ leafletElement } = {}) {
  if ( !leafletElement ) return;
}

What this will do is prevent the rest of our code from running in the event our map isn't ready yet. The mapEffect function itself, as you can see in the Map component, runs inside of an instance of useEffect passing an argument of a ref to the map, allowing us to run some code after our component renders.

So once we have that line, let’s now fetch Santa’s route inside of our mapEffect function:

async function mapEffect({ leafletElement } = {}) {
  if ( !leafletElement ) return;
  let route, routeJson;
  try {
    route = await fetch('https://firebasestorage.googleapis.com/v0/b/santa-tracker-firebase.appspot.com/o/route%2Fsanta_en.json?alt=media&2018b');
    routeJson = await route.json();
  } catch(e) {
    console.log(`Failed to find Santa!: ${e}`);
  }
  console.log(‘routeJson’, routeJson);
}

Let’s break this down:

• We grab Santa’s route via the API endpoint
• Once we have his route, we grab the response in a JSON format to make it easier to work with
• This is all wrapped in a try/catch so we can safely handle any response errors
• Finally, we just log out our response for now

Santa's route object in the web console

Now we have Santa and his route, which means we can see all the destinations in his route. If you dig in the response a little bit, you can see some fun things like how many presents were delivered to each location and the weather at the time!

Follow along with the commit.

Put a pin in his location

We found Santa! ? Now let’s put him on the map.

For our purposes, we’ll need to find the latitude and longitude of Santa. The problem is, we don’t get this exact value defined anywhere, we just get his destinations.

Since we don’t have his location specified anywhere, we can utilize his last known location where presents were delivered. Add the following after our last snippet inside the mapEffect function:

const { destinations = [] } = routeJson || {};
    const destinationsVisited = destinations.filter(({arrival}) => arrival < Date.now());
    const destinationsWithPresents = destinationsVisited.filter(({presentsDelivered}) => presentsDelivered > 0);
const lastKnownDestination = destinationsWithPresents[destinationsWithPresents.length - 1]

Below our request code, we:

• Destructure routeJson to grab destinations into a constant, adding a fallback to an empty object
• Filter the results to only find the destinations that he's visited, using the arrival time from the route object
• Filter the results to find only the locations with presents
• And finally grab the last item from the array, which shows his last known location

At this point in time, 12/23, we don't actually have any destinations, as Santa is still at the North Pole. At any time, we can test this out to simulate a future date by replaceing Date.now() in destinationsVisited with a future date, such as 1577188980000 which would be around 7pm Eastern on 12/24. With that change, we can see what Santa's route actually looks like!

Handle a missing Santa

Now that it's close to Christmas, Santa will still be at the North Pole, so let's handle the case where we don't have a location.

Above the line where we set lastKnownDestination, let's add:

if ( destinationsWithPresents.length === 0 ) {
  // Create a Leaflet Market instance using Santa's LatLng location
  const center = new L.LatLng( 0, 0 );
  const noSanta = L.marker( center, {
    icon: L.divIcon({
      className: 'icon',
      html: `<div class="icon-santa">?</div>`,
      iconSize: 50
    })
  });
  noSanta.addTo( leafletElement );
  noSanta.bindPopup( `Santa's still at the North Pole!` );
  noSanta.openPopup();
  return;
}

Okay so what are we doing here?

• First, we’re checking if we have any destinations with presents, which here we don't
• We first create a LatLng of the center of the map
• We create a Leaflet marker, using that center, with a custom Icon of Santa
• Next we add that Santa marker to the leafletElement, which is our map
• To show a message, we first bind a popup with a custom message and open it
• Finally we return so the rest of the code doesn’t run, as we don’t have Santa at this point

This was a section added after published to handle the API resetting, but you can still follow along with the code I added in context of the rest of the rest of the code.

Follow along in the code.

Pinning Santa

Edit 12/23: This section was originally written with the previous year's API, but this is still a good example of what you'll expect on the response, so you can follow right along.

And as we can see, since we’re looking at last year’s data, Santa is back home at the North Pole.

Santa's last known location in the web console

With his location, we can pull that apart, set up a Leaflet marker instance, and add our old friend to the map. Add the following after our last snippet inside the mapEffect function:

const santaLocation = new L.LatLng( lastKnownDestination.location.lat, lastKnownDestination.location.lng );

const santaMarker = L.marker( santaLocation, {
  icon: L.divIcon({
    className: ‘icon’,
    html: `<div class=“icon-santa”>?</div>`,
    iconSize: 50
  })
});

santaMarker.addTo(leafletElement);

Here we:

• Create a Leaflet LatLng instance with his location
• Create a Marker instance with our newly created LatLng instance
• Add our new Marker to the map

If we refresh our page, you’ll have to zoom out and pan up a little bit, but we'll see Santa on the map!

Santa on the map

Before we move on, let’s give Santa a little holiday cheer to make him easier to find. Find your application.scss file and toss these styles in:

// In src/assets/stylesheets/application.scss

.icon {

  & > div {

    display: flex;
    justify-content: center;
    align-items: center;
    overflow: hidden;
    border-radius: 100%;
    box-shadow: 0 3px 4px rgba(0,0,0,.4);
    border: none;
    transition: all .2s;

    &:hover {
      box-shadow: 0 4px 8px rgba(0,0,0,.6);
    }

  }

}

.icon-santa {
  width: 50px;
  height: 50px;
  font-size: 3em;
  background: white;
}

This just adds a white circle around him, a little drop shadow, and increases the size a bit to make him a little easier to find on the map.

Santa styled on the map

Follow along with the commit.

Drawing his route

The last thing we’re going to do here is draw a path on the map showing his route so we can follow along.

To get started, let’s update our code and add this last bit after our last snippet in the mapEffect function:

// Create a set of LatLng coordinates that make up Santa's route

const santasRouteLatLngs = destinationsWithPresents.map(destination => {
  const { location } = destination;
  const { lat, lng } = location;
  return new L.LatLng( lat, lng );
});

// Utilize Leaflet's Polyline to add the route to the map

const santasRoute = new L.Polyline( santasRouteLatLngs, {
  weight: 2,
  color: 'green',
  opacity: 1,
  fillColor: 'green',
  fillOpacity: 0.5
});

// Add Santa to the map!

santasRoute.addTo(leafletElement);

What we’re doing:

• Creating an array of Leaflet LatLng instances that make up Santa’s route
• Creating a Leaflet Polyline (a multi-point line) using that routes array
• Make that Polyline green
• Add our Polyline to the map

What we get… is a bunch of squiggly lines!

Santa's route on the map

This is expected. This gets technical really fast, but Leaflet by default can only understand 1 “portion” of the map as it wraps around in our browser. What this realistically means, is instead of drawing a line around a globe, the coordinates think it goes from one side of the world to the other as it hits the International Dateline. This is a bit out of scope for this tutorial, but you can check out Leaflet.Antimeridian to learn more and see if you can implement the solution to it.

Follow along with the commit.

A few quick style tweaks

One last thing! And this is completely optional. Let’s make the map a little bit bigger, set the background color to match our oceans, and zoom out a little bit. So let’s make a few changes:

// In src/pages/index.js

const DEFAULT_ZOOM = 1;

We’re setting our default zoom to 1 instead of 2 to allow the map to be zoomed out a bit.

// In src/assets/stylesheets/pages/_home.scss

.page-home {

  .map,
  .map-base {
    height: 80vh;
  }

}

We’re setting our map to a height of 80vh instead of 50vh to make it take up a little more of our screen.

// In src/assets/stylesheets/components/_map.scss
.map {

  &,
  .map-base {
    background: #acd3de;
  }

}

We’re setting the background color of our map to #acd3de instead of $blue-grey-50 which allows us to match the color of the oceans on our map.

What this achieves is being able to see Santa’s full route and Santa on the first view. Additionally, since the map only covers part of the screen, setting the background color of the map allows us to not have a little bit of a weird cutoff.

Santa's route zoomed out

Follow along with the commit.

Want a challenge?

To take this 1 step further, follow along with both how we added the routes and Santa to the map and try to see if you can add a marker to each destination location to show where all of the stops are. Bonus, add a popup to each one that says how many presents were delivered to that location!

To see the answer with some code organization and how I added the gift markers, check out the final version of the Santa Tracker demo.

Final Santa Tracker demo

While you’re there, you can also see how I utilized Leaflet.Antimeridian to fix our map's route.

What did we learn?

Building basic apps with a map isn’t nearly as bad as we thought! We learned how to fetch some data from an API, grab the data we need, and draw representations of that data on a map.

Next time you want to add a map widget to your landing page, try Leaflet. Share what you create on Twitter! Would love to see what you come up with.

I hope you and your family have a fantastic holiday season!

Happy Holidays from Dunder Mifflin

Want to learn more about maps?

You can check out a few of my other resources to get started:

• Anyone Can Map! Inspiration and an introduction to the world of mapping
• How to create a Coronavirus (COVID-19) Dashboard & Map App in React with Gatsby and Leaflet
• How to set up a custom Mapbox basemap style with React Leaflet and Leaflet Gatsby Starter
• How to Create a Summer Road Trip Mapping App with Gatsby and Leaflet
• How to build a mapping app in React the easy way with Leaflet

Want to read some of my other articles? Check out my blog: https://www.colbyfayock.com/2019/12/create-your-own-santa-tracker-with-gatsby-and-react-leaflet/

Not that AAA map under your car seat

Maps have been around for thousands of years, but they’ve become more complex and powerful within the last couple decades simply due to the fact that computers exist. This has enabled the creation of products we use every day - like Google Maps that help us get home from work and avoid traffic, or weather maps that allow us to check real time radar images. Taking that a step further, scientists use maps every day using data from satellite imagery to try to get a better understanding of our humble planet.

This sounds hard…

Building maps

Plot twist, it’s not hard!

Final Space — What a twist!

At least it’s not hard to get started. Thankfully, the parts that are the hardest are already built into libraries that can easily be tapped into with JavaScript.

Enter Leaflet…

Mapping Libraries

There are a few libraries in the mapping space right now (like OpenLayers), but we like Leaflet.

To get started with Leaflet, first include the library’s assets on your page. Next, mount the application onto a root element within the DOM with some basic settings. You can kind of think of it like how React mounts to a DOM node, but Leaflet itself doesn’t use React. Once initialized, Leaflet allows you to start utilizing it’s API to project a basemap, add layers, tiles on those layers, and even start to draw on it.

Basemap? Layers? Tiles?

To get the basic gist, think of a cake. Traditionally, cakes have different layers, some on the bottom, some on the top, some might just cover one side with icing. Your map layers function similarly. The bottom layer, which is your foundation, will be your “basemap”. Below, we’re seeing a snapshot of the 2018 California Camp Fire wildfires on top of NASA’s MODIS Aqua satellite imagery.

MODIS Aqua – California “Campfire” Wildfires

Now, to get a basemap, we need the imagery to produce it, which is where tiles come in. A tile is a single image block that makes up your group of tiles that represent your layer.

_MODIS Aqua single tile and URI scheme – Tile Link_

Your tiles are really just a simple image, but alongside the rest, coordinated by geographic positions and zoom levels, make up what you see when you’re looking at a web map like the basemap shown above. The goal of including these smaller individual pieces rather than 1 huge image is that between dealing with the entire globe, the different zoom levels available, and the resolutions available beyond that, we’re talking about gigabytes upon gigabytes of image assets that just wouldn’t be reliable or realistic to serve as a whole.

Once you’ve established your basemap, you can then overlay additional layers using more imagery, vector tiles, or datapoints that get transformed to layers. In the screenshot below, we’re zoomed in beyond the highest resolution of our basemap. Notice though the imagery on the left, is an individual overlay tile from Digital Globe that provides us with a higher resolution of part of the area surrounding the fire zone.

MODIS Aqua with tile overlay from Digital Globe

Another example on top of that is adding points representing fires collected from NASA’s VIIRS imagery.

MODIS Aqua with VIIRS fire datapoint layer

This allows us to have the context of the basemap as well as being able to cast any type of data we’d like to better understand its effects.

In addition to the VIIRS data, there are many sources of imagery, vector tiles, and datasets published by governments and municipalities that you can use to help build interesting maps and data visualizations. NASA is one good source of these types of assets, but many commercial providers release open access to disaster datasets that help others build solutions around relief efforts.

What’s this about drawing stuff?

Usually when people use maps, they want to look at points of interest. Drawing gives us the ability to frame those areas of interest with different drawing tools such as creating a rectangle using a bounding box tool or drawing a circle. These are simple shapes, but those shapes represent a geographic space that can then be used to gather data about that area.

Rectangular bounding box around Alexandria, VA

React ❤️ Leaflet

Leaflet in itself gives you a lot to work with, but there’s still a lot of manual effort that goes along with it. If you’re used to building a React app, you’re probably not as used to building an entire UI using nothing but APIs based on the browser’s window, and this is where React Leaflet shines.

React Leaflet is a React library that takes the map building and bundles it into intuitive components that represents those parts of the map. Consider the above, where we talked about your basemap and layers to along with it, you might see it looking something along the lines of:

Pseudo map component code

While you would probably expect that it’s not as flexible as utilizing the Leaflet APIs directly, this completely opens up one’s world to being able to easily spin up simple map solutions in an intuitive way without all the effort. After all, at that point, you’re spinning up a React app which you’re probably already familiar with.

Taking it a bit further with Gatsby

You want it easier, you say? You want me to build the map for you, you say? Well, you’re in luck! First, let’s give a brief introduction to another tool.

For the unfamiliar, Gatsby is a javascript framework that allows developers to easily spin up full, completely working React applications in a matter of minutes. They have all the nuts and bolts in place and moved out of the way to let you do what you do best: focus on the important parts of your application.

The beautiful part about Gatsby is that it supports extensions of their default installation which they call Starters. What better way to make it easier for people to spin up maps than to create a Gatsby Starter?

Gatsby Starter Leaflet

Combining the ease of a Gatsby Starter and the flexibility of Leaflet, we have Gatsby Starter Leaflet. This simple tool allows you to scaffold a new React application running Leaflet along side React Leaflet in the matter of seconds (or minutes depending on your computer).

Starting page for Gatsby Starter Leaflet

With a few basic commands, including installing your dependencies, you have an app that’s ready for you to start building on top of to create maps that will save the world. Even better, it includes some out of the box integrations like OpenStreetMap and an easy to setup map service configuration to the foundational React Leaflet component APIs that allow you to easily get product and have more flexibility to create smarter Mapping apps.

There’s gotta be some downsides…

No library or framework isn’t without its downsides. The more complicated your mapping application gets, the more pain points you run into. Here are a few from our experience that might help you settle in.

Bob Kelso — Scrubs

Leaflet — from the Window to React

Trying to manage state and the lifecycle between your Leaflet map and your React components can prove to be tricky. Trying to constantly maintain and update your component using props will immediately start to create issues between stale map state or memory leaks due to maps not properly unmounting when the component does.

Advice: mount your map with React, interact with it using the native Leaflet API. Once your map is rendered and settled down, you can use Leaflet to fly your user around the world and draw on your map without running into the state issues of multiple component renders.

Limited Use of Public Tiles

While there are a few tiling services available that allow you to easily plug in and create a basemap, not all of these are actually intended to be heavily used. Take for instance OpenStreetMap, while you may be able to play around and develop basic solutions on their public endpoint, heavy use will be throttled and potentially blocked without explicit permission from those who maintain their servers.

Advice: when you’re just starting out playing around, you shouldn’t have to worry too much. Worst case the maps will be a little slow to download. As your application starts to get more traffic, you’ll want to look into spinning up your own tiling service or paying for an out of the box solution such as Mapbox.

Get mapping!

It has never been easier to build a map-based web application. There is enough tooling, documentation, and public data available to help you get off the ground and start building maps to explore our world in the time it takes you to set up a blog or static website. So what are you waiting for?

Go explore with Dora!

Originally published at https://www.element84.com/blog/mapping-with-leaflet-and-react

Nowadays, almost all mobile applications have a maps feature. I had to integrate Google Maps to my React Native application, and the only choice was react-native-maps by Airbnb (it’s the only one still supported by the React Native community).

I found several tutorials on how to set up this library, but none fully worked for me. This was because I had to run on both iOS and Android platforms and also support Google Maps for iOS.

Let’s create a React Native application from scratch using react-native-cli to show, step by step, how everything is installed. If you want to integrate react-native-maps for your existing app, skip Step 1.

Step 1: Install and set up React Native application

If you haven’t installed the React Native command line interface, run: npm install -g react-native-cli. Now you can create your project, simply using: react-native init ReactNativeMaps

Here are the dependency versions at the time of building this project:

• “react”: “16.6.1”
• “react-native”: “0.57.5”
• “react-native-maps”: “0.22.1” — we will install this one later.

Now you can try to run your app, react-native run-ios or react-native run-android . Usually, this works without any problems.

Step 2: Add and Link react-native-maps package

Now let’s install react-native-map: npm install --save react-native-maps after installing the package you should link it to your native apps: react-native link react-native-maps.

You also got this? Cool, now we can continue.

Step 3: Set up Apple Maps (iOS)

It will be easier if we set them up separately by platform, so let’s first do it on iOS. Before integrating Google Maps, we will check if Apple Maps works correctly. Add the following code to your current rendering component where you want to render your MapView.

import MapView from 'react-native-maps'

export default class App extends Component<Props> {  render() {    return (      <MapView        style={{flex: 1}}        region={{          latitude: 42.882004,          longitude: 74.582748,          latitudeDelta: 0.0922,          longitudeDelta: 0.0421        }}        showsUserLocation={true}      />    );  }}

You can test whatever location you want, just specify the appropriate Latitude and Longitude. As you can see, I enabled user location simply by adding the showUserLocation prop to the MapView component. If you are running on the real device you will see your current location.

So, as you can see, by default Apple Maps is already working. More than that, if you linked everything correctly and enabled the user location, it’s actually done a lot of things for us (the user permission for the location with a default message). If you came from native iOS development, then you probably know what is an info.plist file.

Step 4: Install Cocoapods and ‘GoogleMaps’ package (iOS)

Apple Maps was easy, right? Agreed — so let’s see what Google Maps has for us. We have to install Google Maps SDK for iOS. We will use Cocoapods. If you haven’t used it before, run sudo gem install cocoapods.

Now you have to create a Podfile where you will specify the dependencies of your iOS application. Navigate to your iOS/ folder in your React Native app and run: pod init or you can use touch Podfile you should have something similar to this:

# platform :ios, '9.0'

target 'ReactNativeMaps' do

# Pods for ReactNativeMaps

pod 'GoogleMaps'

end

As you can see, I added the pod GoogleMaps and now we have to install it. If you are still on iOS/ folder, run: pod install . If you try to run it now, you will probably get an error:

Okay, let’s do what it wants. Now we should open xCode workspace.

Navigate to AirGoogleMaps folder from node_modules/

And drag it to the top of your xCode project

Please try to build your xCode project, if you are failing

You should add HAVE_GOOGLE_MAPS=1Preprocessor Macro to Build Settings

Step 5: Get Google Maps API key, Run iOS app with Google Maps

So now we have to generate a Google Maps API key.

Copy your API key and add to AppDelegate.m file.

#import <GoogleMaps/GoogleMaps.h>

[GMSServices provideAPIKey:@"YOUR_API_KEY"]

Now you can tell your MapView component that you are ready to use Google Maps.

Oh yesss, please run your iOS app. And you will get Google Maps.

I hope.

Step 6: Let’s try Android now

Okay now we can quit xCode and let’s just try react-native run-android. If you are getting the same as this:

check your android/app/build.gradle file. And replace this:

compile project(':react-native-maps') with this:

implementation(project(':react-native-maps')){        exclude group: 'com.google.android.gms', module: 'play-services-base'        exclude group: 'com.google.android.gms', module: 'play-services-maps'    }implementation 'com.google.android.gms:play-services-base:12.0.0'implementation 'com.google.android.gms:play-services-maps:12.0.0'

Oh, and don’t forget to add API_KEY to AndroidManifest.xml file.

<application>   <meta-data      android:name="com.google.android.geo.API_KEY"      android:value="YOUR_API_KEY"/></application>

Yes, now your app is running on both platforms. Please check the react-native-maps repo for more fun things that you can do with your MapView component.

Conclusion

Hope my first article on Medium was helpful for you. Please, if you see any mistakes don’t hesitate to leave a comment, I will appreciate your comments!

Or, how to choose the best way to walk to the beach after work

It was a cool autumn evening when Hila Kloper and I were thinking of going to the beach after work. The beach is about 2.5Km away from the office.

We were even considering strolling down the streets of Tel Aviv, willing to stretch our path to 3Km, and thinking to ourselves “mmm we wonder how far this stretch can take us?”

Well, long story short, we didn’t go to the beach. Instead, we wrote a script that draws an ellipse around the office and the beach. The ellipse covers the city area we may go through if we ever decide to go to the beach after work.

When developers want to do something fun outside and they end up writing a script about it instead.

It’s the Ellipse of Life

Or - why should we care about ellipses?

A circle is in some way the “natural” area around one point. An ellipse is the “natural” area around two points or a line. To name a few examples, bodies of mass move in elliptic orbits, ellipses represent the distortion caused by projecting a 3D map on 2D, and ellipses are also an accurate way to plot confidence of noisy GPS data (and confidence areas in 2D data in general).

In our case, we wanted to draw an area around the line starting at our office and ending at the beach. The easiest solution we found for drawing ellipses involved shapely and pyplot. It still required some modifications due to our GPS and map constraints.

So, if you are here because you are looking for an easy copy-pastable code that draws an ellipse on a map — you can go to this repository we made. If you are also interested to learn how we found the complete solution to our problem, you are welcome to join us for the ride. We rediscover elementary geometry, learn about coordinates systems, and play around with some math code.

Girls Just Wanna Have Ellipses

Us: “Oh there must be a package somewhere that can draw an ellipse on a map!”
The Internet: “No there isn’t.”
Us: “But there must be a simple copy-pastable code somewhere!”
Stackoverflow: “I have incomprehensible ones if you want.”
Us: “Well, OK, we’ll take an hour and make one ourselves!”
Reality: “…”

Figuring out what an ellipse actually is was the first challenge.
Wolfram Alpha told us that an ellipse is the set of points that have the same sum-of-distances from two mutual centers. Or something like that. Wolfram Alpha can be rather cryptic sometimes. But they have a gif so that’s nice.

Ah… now that’s clear.

So all we have to do is make sure we have these inputs:

• p1, p2 - GPS coordinates.
• r - the radius which is actually the sum of distances from a point on the ellipse to the two centers.

Then follow this plan:

1. Find a and b, the axes of the ellipse.
2. Draw an ellipse around the origin (0,0) measured in meters.
3. Move the ellipse to the center between the input GPS locations.
4. Rotate according to the angle between the input GPS locations.

And that’s it.

Sounds simple enough, right?

The Long and Winding Road (That Leads to Ellipse)

Step 1. Find the axes.

Here we needed to do some basic Pythagorean algebra. This image from Wikipedia was somewhat helpful:

Computing c from GPS coordinates was easy thanks to haversine package.

def GetEllipseAxisLengths(p1_lat, p1_lng, p2_lat, p2_lng,
                          radius_in_meters):
    c2 = haversine((p1_lat, p1_lng), (p2_lat, p2_lng)) * 1000.0
    if radius_in_meters < c2:
        raise ValueError("Please specify radius larger than the               
                          distance between the two input points.")
    a = radius_in_meters / 2.0
    b = sqrt(pow(a, 2) - pow(c2 / 2.0, 2))
    return a, b

Step 2. Draw an Ellipse Around the Origin.

What we did here is that we took evenly spaced points on the x axis and for each one found the two points on the ellipse that project to it:

Luckily we found this lovely equation on Wikipedia.

def GetEllipsePointInMeters(a, b, num_points):
    """
    :param a: length of "horizontal" axis in meters
    :param b: length of "vertical" axis in meters
    :param num_points: (half the) number of points to draw
    :return: List of tuples of perimeter points on the ellipse, 
             centered around (0,0), in m.
    """
    x_points = list(np.linspace(-a, a, num_points))[1:-1]
    y_points_pos = [sqrt(pow(a, 2) - pow(x, 2)) * 
                    (float(b) / float(a))
                    for x in x_points]
    y_points_neg = [-y for y in y_points_pos]

    perimeter_points_in_meters = 
        [tuple([-a, 0])] + \
        [tuple([x, y]) for x, y in zip(x_points, y_points_pos)] + \
        [tuple([a, 0])] + \
        list(reversed([tuple([x, y]) 
                       for x, y in zip(x_points, y_points_neg)]))
    return perimeter_points_in_meters

Step 3. How Do You Even Add Meters to GPS?

Well this was a tricky one, and the answer lies in understanding that

Unleashing the secrets of elementary geometry.

Fun fact: the Earth’s radius is around 6371000 meters on average!

def AddMetersToPoint(center_lng, center_lat, dx, dy):
    """
    :param center_lng, center_lat: GPS coordinates of the center  
           between the two input points.
    :param dx: distance to add to x-axis (lng) in meters
    :param dy: distance to add to y-axis (lat) in meters
    """
    new_x = (center_lng + (dx / R_EARTH) * (180 / pi) /   
             np.cos(center_lat * pi/180))
    new_y = center_lat + (dy / R_EARTH) * (180 / pi)
    return tuple([new_x, new_y])

Step 4. Rotate.

This time, the wonders of the internet did not fail us (as they did on our major ellipse-drawing task). We found shapely package to do the rotation for us. The one trick to remember here is that you can’t rotate the points one by one. Rather you should form a shape first, and then rotate the entire shape.

def GetEllipsePoints(p1_lat, p1_lng, p2_lat, p2_lng, 
                     perimeter_points_in_meters):
    """
    Enter ellipse centers in lat-lng and ellipse perimeter points    
    around the origin (0,0), and get points on the perimeter of the 
    ellipse around the centers in lat-lng.
    :param p1_lat: lat coordinates of center point 1
    :param p1_lng: lng coordinates of center point 1
    :param p2_lat: lat coordinates of center point 2
    :param p2_lng: lng coordinates of center point 2
    :param perimeter_points_in_meters: List of tuples of perimeter 
           points on the ellipse, centered around (0,0), in m.
    :return: List of the points we really want, tuples of (lat,lng)
    """
    center_lng = (p1_lng + p2_lng) / 2.0
    center_lat = (p1_lat + p2_lat) / 2.0
    perimeter_points_in_lng_lat = \
        [AddMetersToPoint(center_lng, center_lat, p[0], p[1])
         for p in perimeter_points_in_meters]
    ellipse = LineString(perimeter_points_in_lng_lat)

    angle = degrees(atan2(p2_lat - p1_lat, p2_lng - p1_lng))
    ellipse_rotated = affinity.rotate(ellipse, angle)

    ellipse_points_lng_lat = list(ellipse_rotated.coords)
    ellipse_points = [tuple([p[1], p[0]]) 
                      for p in ellipse_points_lng_lat]
    return ellipse_points

Surprise! Step 5. Draw on s2 Map!

We wanted to present the ellipse nicely on an s2map. Apparently you can do that by opening the URL from inside your script. We used subprocess to do that.

def OpenS2Map(points):
    url = \
      "http://s2map.com/#order=latlng&mode=polygon&s2=false" \
      "&points={}".format(str(points).replace(" ", ","))
    cmd = ["python", "-m", "webbrowser", "-t", url]
    subprocess.Popen(cmd, stdout=subprocess.PIPE, 
                     stderr=subprocess.STDOUT).communicate()

OK. can we go the beach now?

The Neighbor’s Ellipse Is Rounder

You might notice our ellipse is not perfect. The points are evenly spaced on the axis between the centers, but they are not evenly spaced on the perimeter of the ellipse. The GPS->meters->GPS transformation might result in loss of meters here and there. But hey, done is better than perfect, and we have to leave something to do for the next time we want to go to the beach, right?

In the past year, the grid map style visualization has gained a lot of popularity in the US [2,4]. It has a quite a few nice properties, which inspired me to create one for Thailand.

The rest of this article will explain grid maps, and how I created the grid map for Thailand map you see above.

But if you are interested in using the map already without reading the details of how to create one yourself, jump straight to my gridmap-layout-thailand github repository.

What is a Grid Map, and what are its properties?

In a grid map, each region is represented as a tile of the equal shape and size. The tiles are placed to fit within a grid at positions that approximate real geographic position. If the tile is a square, the grid is rectangular. If the tile is a hexagon, then the grid is like a honeycomb. See the US maps below:

_Maps of the US: (left) Hexagon Tile Grid Map (center) Square Tile Grid Map (right) Geographic Map. Source: [NPR Blog](http://blog.apps.npr.org/2015/05/11/hex-tile-maps.html" rel="noopener" target="blank" title=")

Most of grid map visualizations are choropleth maps that use colors to encode values, such as amount of rainfall, average population age, or political alignment. Creating choropleth maps from geographic maps has some disadvantages, because the different sizes of each region introduce biases while interpreting the results. Also, many small regions are often too small to be notice on a map.

Pros: grid maps do not introduce biases due to different sizes of the regions, making it an interesting choice when creating a choropleth map. Small regions are now guaranteed to be big enough to be seen. It’s also easier to implement and faster to load than a geographic map.

Cons: The positions of the regions are only approximations, and could be inaccurate. For example, some adjacent regions may not appear adjacent on the grid map. It also distorts the distance between regions.

Creating Grid Map for Thailand

Here are the requirements:

• The overall map still looks similar to the geographical shape of Thailand. The neighboring regions should appear adjacent or close by.
• Use square tiles for ease of curation and application. For example, this map can be drawn in Excel [3] or Google Sheets easily.
• The map does not have any holes in the middle to avoid confusion.

Of course, the most straightforward approach to create this map is to draw the map manually from scratch. However, I would like to save some energy with a semi-automatic approach:

1. For each province, create one rectangle centered at its centroid.
2. Use a force-directed simulation to detect collisions between rectangles and remove overlaps. Each rectangle has its own center of gravity at the centroid of its province (multi-foci force-directed layout). The solid lines in the figure below show displacements of the rectangles from their ideal positions.
3. Snap the rectangles to a rectangular grid.
4. Export results from Step 3 as CSV file and manually curate in Google Sheets or Excel. The goal of this step is to remove unnecessary gaps, connect the map into one contiguous piece, and adjust the positions of some provinces.
5. Done! The new map only requires 40% of the original space.

Usage

The output from this process can be used as JS, CSV or JSON files. Please see gridmap-layout-thailand on GitHub for instructions. The code I used for steps 1–5 above are also in that repo.

Lastly, this method still depends a lot on manual curation at the end, which may not produce the best optimization. If you have any suggestions or would like to recommend a better approach, the comment box below is yours. :)

References

[1] Mike Bostock. “Multi-Foci Force Layout” bl.ocks.org Published 11 February 2012
[2] Danny DeBelius. “Let’s Tesselate: Hexagons For Tile Grid Maps” NPR Blog. Published 11 May 2015
[3] Caitlin Dempsey Morais. “How to Make a Tile Grid Map Using Excel” GIS Lounge. Published 10 November 2015
[4] Nathan Yau. “The Great Grid Map Debate of 2015” Flowing Data. Published 12 May 2015