Configure Mapbox

The Mapbox provider renders maps, supplies location suggestions, and converts between addresses and coordinates. MyListing uses a public Mapbox access token in both browser requests and server-side Geocoding API v5 requests.

Mapbox is a metered third-party service. Its account includes usage allowances, but requests can become billable; review current pricing, set account controls, and monitor token statistics before launch.

Create a production public token

1. Create or sign in to a Mapbox account.
2. Open Access tokens and create a dedicated token for this site.
3. Use a public token beginning with pk.. Never paste a secret token beginning with sk. into MyListing because the value is sent to visitors’ browsers.
4. Keep only the public read scopes needed to load maps, styles, fonts, and geocoding. Do not grant write or account-management scopes.
5. Save and copy the token.

Mapbox creates a default public token for development, but that token cannot use normal scope management or URL restrictions. A dedicated production token is easier to restrict, monitor, rotate, and isolate from other sites. See Mapbox’s access-token security guidance.

Add the token to MyListing

1. Go to Theme Tools → Map Services.
2. Under Provider, select Mapbox.
3. Paste the token into Mapbox API Access Token.
4. Set Language. The default detects the browser language; Local language on each place is also available.
5. Under Autocomplete returns results for, select the location types the directory needs. Leaving it empty requests all types supported by the service.
6. Optionally limit Autocomplete returns results in to one or more countries.
7. Optionally add Custom Map Styles with a label and a Mapbox style URL (recommended) or style JSON.
8. Select Save settings and test listing submission, a single-listing map, Explore, and any address import.

MyListing also includes Standard, Light, Dark, Outdoors, Satellite, navigation, and guide skins for Mapbox. A style changes map appearance; it does not change autocomplete filters or stored listing coordinates.

Apply URL restrictions carefully

URL restrictions reduce abuse of the token in browser requests. Include every production and staging origin that actually loads a map, then verify requests from each hostname.

One token is also used by the server

A URL-restricted token can return 403 Forbidden when MyListing sends a Geocoding API request from WordPress because that request has no browser referrer. This commonly affects imports and address-only saves. Temporarily removing URL restrictions can unblock a controlled import, but restore them immediately afterward, monitor usage, and rotate a token that may have been abused. MyListing’s current settings do not provide separate browser and server Mapbox tokens.

Geocoding v5 limitations

The current integration calls Mapbox Geocoding API v5. The settings still list Points of interest and Landmarks, but Mapbox removed POI data from Geocoding v5. Those choices therefore do not restore restaurants, businesses, or landmark suggestions. Address, postcode, locality, place, district, region, and country searches remain within the v5 feature model.

Mapbox recommends its Search Box API for POI search, but MyListing’s Mapbox integration does not call that API. Switching products in the Mapbox account does not change the endpoint used by the theme.

Troubleshoot Mapbox

• 401 Unauthorized usually means the token was deleted, refreshed, mistyped, or is otherwise inactive.
• 403 Forbidden usually points to missing scopes, a URL restriction mismatch, or an account restriction.
• If the map loads but suggestions fail, inspect browser network requests to api.mapbox.com, then check token scopes, usage, and the selected autocomplete types.
• If browser suggestions work but an import fails, review the URL-restriction warning above.
• If only POI or landmark results are missing, that is a Geocoding v5 limitation rather than a token error.
• If a custom style fails, confirm the style is accessible to the token and that the full mapbox://styles/... URL was saved.
• Confirm Mapbox remains selected under Theme Tools → Map Services after saving; configuring a token does not select the provider automatically.

Mapbox’s token error guide and Geocoding v5 reference provide the service-specific response details.

Problems that started after upgrading from a MyListing version older than 2.9 may require the locations and work-hours migration.

Next: Repair locations after an older upgrade →