Setting up the map: MapBox key, starting point and zoom

Every map MLSImport draws in standalone mode is configured in one place: the Maps tab of MLS Import Design Settings. Six settings live there, and the three that matter on day one are the MapBox key, the starting point and the default zoom.

Maps work with none of them set. The tiles come from the free OpenStreetMap servers, which are slower than a paid tile service but cost nothing and need no account.

Before you start

These settings exist in standalone mode only, which is the mode that runs MLSImport on any WordPress theme. On WpResidence, WpEstate, Houzez and Real Homes the maps belong to the theme, and the map key is entered in the theme’s own options. WpResidence, for example, can draw with either Google Maps or MapBox and asks for that key in its theme settings.

Which maps these settings control

1. The map on a single property page.
2. The Map with Listings page block.
3. The map half of the Half Map block.

All three read the same settings, so a change applies everywhere at once.

Adding a MapBox key

1. Create an account at mapbox.com and copy your default public access token.
2. Open MLS Import Design Settings and go to the Maps tab.
3. Paste the token into MapBox API KEY.
4. Click Save changes.

Expected result: all three maps switch to MapBox tiles on the next page load. The look changes slightly and the tiles load noticeably faster on a busy page.

Clearing the field returns every map to OpenStreetMap. Nothing else about the maps changes, since only the tile images come from MapBox. Your listings, pins and clusters are drawn by MLSImport either way.

The starting point

Starting Point Latitude and Starting Point Longitude set the fallback centre, and fallback is the important word. When a map has results it fits the view to those results and ignores this setting completely. The starting point is used only when a map has nothing to show.

Enter plain numbers, for example 25.761681 and -80.191788 for Miami. Both fields have to be filled for either to be used.

Leaving them blank has a visible consequence. A map with no results and no starting point opens at latitude 0, longitude 0 at world zoom, which is a point in the Atlantic Ocean. A visitor who runs a search that matches nothing gets a map of the entire planet centred on open water.

The default zoom

Default Maps zoom (1 to 20) runs from 1, the whole world, to 20, an individual street. The default is 11, which shows a city and its surroundings.

It does two jobs. It sets the zoom of the map on a single property page, and it is the zoom used with the starting point when a listings map has nothing to fit to. A value outside 1 to 20 is clamped back into range rather than rejected.

For a single property, 15 to 17 shows the neighbourhood without exposing the exact house to a casual viewer. For a citywide site, leave 11 alone.

If it does not work

1. The map area is grey with no tiles. The MapBox token is wrong, expired, or restricted to a domain that is not yours. Clear the field, confirm the map returns on OpenStreetMap tiles, then re-copy the token.
2. The map ignores the starting point. That map has results, and fitting to results always wins. Run a search that matches nothing to see the starting point in use.
3. No map at all on a property page. That listing has no coordinates. A property with no latitude and longitude has no map section to draw.
4. Nothing changes on a WpResidence or Houzez site. These settings apply to standalone mode. In a supported theme the map is the theme’s, and so is the key.

Frequently asked questions

Is a MapBox account required to use the maps?

No. With the key field empty the maps use OpenStreetMap tiles, which are free and need no account. A key buys speed and a different tile style, nothing else.

Does a MapBox key cost anything?

MapBox meters map loads and publishes the current free allowance on their pricing page. A normal property site sits well inside it, but read their page rather than ours before relying on the number.

Can I use Google Maps instead?

Not in standalone mode. The maps are built on Leaflet, which draws from a tile source, and the two supported sources are OpenStreetMap and MapBox. The supported themes offer Google Maps through their own settings.

Do these settings apply to the map in the Customizer preview?

Yes. The Customizer edits the same options as the settings page, so a starting point or zoom changed there is the same value the front end reads.

Related

1. How pin clustering works
2. Listings missing from the map
3. The Map with Listings block
4. The Half Map block
5. The Design Settings page

Send us the page with the map that is not behaving and we will tell you which of the six settings is responsible.