NICFI Basic

Display Planet NICFI imagery on an interactive Mapbox web map.

This template will help you kickstart your web map with NICFI imagery and demonstrate how to add in NICFI imagery as a layer. Add customizations to your web map on top of this foundation.

There are a few resources you'll need to get started:

• Sample code template
• A text editor tool (e.g. Atom, VSCode, JSFiddle, Glitch) to write and edit your code.‍
• Mapbox account and access token
• Planet NICFI API key
• A way to publish your web map online - check out these three options.

Open a text editor and create a file called index.html. Set up the document by downloading or copying the demo code into your new index.html file.

Without an access token, the rest of the code will not work.‍

Login or create a free Mapbox account. Find your access token on your Access tokens page or the main page you sign into your Mapbox account.

Note: We recommend using the URL restriction feature on the token to avoid token misuse and want to emphasize that only public tokens should be posted to public repositories. Find out more information about how to securely manage your access tokens.

// YOUR TURN: Add your Mapbox access token
   mapboxgl.accessToken = "{YOUR_MAPBOX_ACCESS_TOKEN}";

The template is set up to load the map viewing the entire world. If you want the map to load looking at a particular location, you can modify the 'center' and 'zoom' settings. The center point is a pair of longitude, latitude coordinates. Zoom ranges from 0 to 22, with 0 being the lowest zoom level (fully zoomed out) and 22 being the highest (fully zoomed in).

If you want to also set the map’s pitch (tilt angle) and/or bearing (the direction the view is facing) you can add those parameters below the 'zoom` line.'

If you’re not sure what numbers to use, try experimenting with the Location Helper demo.

const map = new mapboxgl.Map({
       container: "map",
       style: "mapbox://styles/mapbox/satellite-streets-v11",
       // YOUR TURN: Set the center coordinates and zoom level for your map
       center: [2, -2],
       zoom: 2,
       hash: true
   });

Note: The template uses the Mapbox Satellite Streets basemap style to display underneath any NICFI imagery layered on top. You may modify this to any other Mapbox style, including a custom style, if needed.

To access NICFI imagery, you must register with Planet and be granted a NICFI API key. This is different from other Planet access keys that you may already have.

// YOUR TURN: Add your Planet NICFI API key
const NICFI_API_KEY = "{YOUR_NICFI_API_KEY}";

The template map will display NICFI imagery from a single time period. To specify which time period to show, you must define the year and month.

Note: There was a formatting change for periods starting in September 2020, when the NICFI imagery frequency switched to monthly. For September 2020 and more recent format the period like this:

"Sep 2020": "2020-09"

But for periods before September 2020, format the period like this:

"Jun 2020 - Sep 2020": "2020-06_2020-08"

The template lists multiple time periods. You can select one of those, or update the list to use more recent imagery. The map will only display the imagery from the most recent time period in your list. (To show multiple time periods, see the next two tutorials for NICFI Viewer and NICFI Compare.)

You’ve made a web map! But it isn’t a webpage yet… to do that we need some way to host a webpage. There are many different ways to host a web map. You can add your code to a web page that you already manage, or you can explore web hosting options. Read this guide to learn how to publish your finished map on GitHub, Netlify, or Glitch.

Need more help? Ask questions on Stack Overflow or contact Mapbox Support. If you are working on a social good project, contact the Mapbox Community Team.

Want to share what you’ve built? Tweet it with #builtwithmapbox

It is possible to tilt your map to show an angled view, which is especially useful if you want to show 3D terrain. 3D terrain and sky settings are already included by default in the template code and will be apparent if you change the 'pitch' of the map - either by holding down your ‘control’ key when you click and drag on the map, or by setting a 'pitch' value when the map first loads (see the earlier step on Select a center point and zoom level).

Learn more about setTerrain and sky options.

If you want users to be able to search for a location and automatically move the map there, you can add a geocoder search bar by adding eight lines of code before the </script> tag at the end of the code.

map.addControl(
       new MapboxGeocoder({
           accessToken: mapboxgl.accessToken,
           mapboxgl: mapboxgl,
           marker: false,
           collapsed: true
       })
   );

If you want to help users zoom in or out on the map, you can add standard navigation controls with a single line of code before the </script> tag at the end of the code, as shown in this example.

// Add zoom and rotation controls to the map.
map.addControl(new mapboxgl.NavigationControl());

If you want to limit where users can view on the map to keep them focused on an area of interest, you can limit panning and zooming on the map:

Restrict map panning to an area

Disable scroll zoom