MatrixMap documentation

MatrixMap puts interactive maps on your WordPress site without an API key or an account. One visual builder makes three kinds of map:

• Maps with your places, popups, categories, shapes and GPX, KML or GeoJSON files.
• Store locators that let visitors find the nearest of your locations by address, postcode or their own position.
• Region maps: the world, a continent, a country or its regions as clickable shapes, coloured with your own data.

There is no limit on the number of maps or locations. A single map can hold up to 5,000 places.

Requirements: WordPress 6.5 or newer and PHP 7.4 or newer.

1. In WordPress go to Plugins → Add New, search for “MatrixMap” and click Install Now, then Activate. You can also upload the plugin zip under Plugins → Add New → Upload Plugin.
2. A MatrixMap menu appears in the admin sidebar with Dashboard, Maps, Add New Map, Locations, Categories, Analytics, Settings, Import & Tools, Free vs Pro and Docs.
3. Open MatrixMap → Dashboard. The Get started checklist walks you through your first map, your locations, putting a map on a page and checking style and privacy.

Maps work straight away with free vector maps. Every setting under MatrixMap → Settings is optional.

Where things are

1. Go to MatrixMap → Add New Map.
2. Type a Map name. Only you and screen readers see it, not visitors.
3. Pick a starting point: One location, Several places with a list, Route, trail or area, Store locator, Countries we serve, Data map by country, US states, or any country’s regions, or Start with a blank map. Then click Create map.
4. The map builder opens with its tabs on the left and a Live preview on the right. You can switch the preview between Desktop, Tablet and Phone widths.
5. Add places: in the Places tab type an address and click Search, or click Add place and then click the map.
6. Click Publish in the top bar, or press Ctrl+S (⌘+S on a Mac). After that the button reads Update.
7. Put the map on a page. Add the MatrixMap block and choose the map, or paste the shortcode shown in the top bar, for example [matrixmap id="12"].

The top bar also has a button that switches full-screen editing on and off. Your browser remembers the choice.

The map builder

Every map is edited in the same builder. The tabs depend on the map type:

You can change the type under Settings → Map type. Your places are kept, but each type has its own settings.

In the preview bar, Fit all zooms to show every place. Use this view saves what you see as the starting view. Click Fixed view × to go back to fitting all places automatically.

• Map look: go to MatrixMap → Settings → Maps & style. Vector maps are the default, need no key and are free for any traffic. Set a Brand colour so buttons, markers, clusters and highlights match your theme.
• Privacy: go to MatrixMap → Settings → Privacy & consent. With a consent plugin installed, maps wait for consent by default. You can also make every map click-to-load. Region maps contact no outside service at all.
• Many addresses? Go to MatrixMap → Settings → Address search. The free OpenStreetMap search allows about one lookup per second. For large imports, choose a service with a key.
• Store locator: add your locations under MatrixMap → Locations, or import a spreadsheet, before you build the locator.

MatrixMap Pro is a separate plugin that adds its features to the same MatrixMap screens: Settings, Import & Tools, Analytics, the Dashboard and the map builder. There is no separate Pro menu.

1. Make sure the free MatrixMap plugin is installed and active. Pro needs it and shows a notice if it is missing.
2. Download the Pro zip from your purchase email or your account, then upload it under Plugins → Add New → Upload Plugin and activate it.
3. Go to MatrixMap → Settings → License, paste your License key and click Activate license.

The licence enables one-click updates and support. Every Pro feature keeps working without an active licence, including after it expires. To move a licence to another site, click Deactivate on this site first.

A licence key for a bundle is refused. Use the MatrixMap Pro key from your purchase email.

1. In the Places tab, type an address, city or landmark under Add a place by address and click Search. Coordinates work too, for example 48.858, 2.294. If there are several matches, choose the right one.
2. Or click Add place and click the map. Press Esc to stop adding.
3. Click a place in Places on this map to edit it.

Each place has:

• Title, Address (click Find to move the place there), Latitude and Longitude. Drag the marker to fine-tune it.
• Popup text with bold, italic, links and lists, a Popup image, a Phone number and a Button link with its own Button text (default “More info”) and Open in a new tab.
• Marker style: Pin, Round icon, Dot or Your own image, with a Colour, a Symbol and a Size. Leave the colour empty to use the category colour.
• Categories, Open this popup when the map loads and Hide this place for now.

Use Duplicate or Delete place at the bottom of a place.

Add many places at once

The Import tab fills a single map quickly:

• Paste addresses, one per line, then click Find and add.
• Import a file: a CSV with columns such as Name, Address, City, Country, Latitude, Longitude, Description, Phone, URL and Category, or a GeoJSON file with points.
• Export: Download CSV or Download GeoJSON of the map’s places.

Rows with coordinates are added instantly. Addresses are looked up at about one per second with the free service. Click Stop to cancel a long import.

To use the same places in several maps and in store locators, add them as Locations instead.

Categories group places. Markers take the category colour, and visitors can filter the map by category. Add them with Add category, then give each a name, a colour and a symbol.

In the Settings tab:

• List and filters → Show a list of places next to the map adds a list Beside the map or Below the map. It also helps keyboard and screen reader users. Options: Search box above the list and Category filter buttons.
• Clustering → Group nearby places into numbered clusters. This is recommended for more than about 50 places. Cluster radius sets how close places must be (default 60).
• Locations library → Also show locations from MatrixMap → Locations: choose No, All locations or Locations in these categories. Changes to a location then show on every map that uses it.

The Shapes tab draws delivery areas, service zones, routes or a radius around a place.

1. Click Draw area, Draw line or Draw circle.
2. For an area or line, click the map to add points, then click Finish. Undo point removes the last point. For a circle, click the centre and set Radius (metres).
3. Give the shape a Title and Popup text, and set Line colour, Fill colour, Line width, Fill opacity and Dashed line.

Connect places → Draw a line through all places in list order joins your places with a straight line.

Add GPX, KML and GeoJSON files

Show hiking tracks, routes, boundaries or data files on a map. In the Shapes tab, under GPX, KML and GeoJSON files:

1. Click Upload or choose a file to use the Media Library, or paste a web address into Or a file URL and click Add.
2. Set the Title and Colour.
3. For GeoJSON, Popup shows property picks which property is shown when a feature is clicked (default: name).
4. Tick Zoom the map to this file if the map should frame it.

With MatrixMap Pro, a map can draw the real road route through its places instead. See Planned routes and elevation profiles.

In the Style tab, choose the Map engine for this map, or keep Site default to follow MatrixMap → Settings.

With a MapTiler key, vector maps also offer MapTiler Streets, Outdoor, Satellite and Dataviz.

For Google maps the builder preview uses OpenStreetMap, while visitors see Google Maps. Google map styling is managed with a Map ID in the Google Cloud Console.

If a visitor’s browser can’t run vector maps (WebGL switched off or unsupported), the map uses image tiles instead of staying blank.

MatrixMap Pro adds a heatmap and a 3D globe view to this tab. See Heatmap and globe view.

The Settings tab of a map:

• Size: Height (for example 480px or 60vh), Height on phones and Width.
• Starting view → When the map opens: Show all places, Use a fixed centre and zoom, or Use the current preview view. You can also set Maximum zoom and Minimum zoom.
• Controls and scrolling: Buttons position (a corner, or Hidden), Zoom buttons, “Show my location” button, Full screen button, Mouse wheel, Touch screens and Allow dragging the map.
• Popups: Open popups on click or mouse hover, Popup width (px), and the Directions button (Google Maps, Apple Maps, Waze).
• Privacy → Load this map: Site default, After consent, Only after a click on “Load map” or Immediately.

Every post of a type, such as properties, events or members, can appear on a map using location fields you already have. The map updates when posts change.

1. Open a map and go to the Places tab. Under Posts on this map, turn on Show posts on this map.
2. Choose the Post type.
3. Under Position from, pick Latitude and longitude fields (enter the Latitude field and Longitude field keys, default lat and lng), An ACF map field (a Google Map or OpenStreetMap field), or An address field. Addresses are found on the map when a post is saved.
4. Optionally limit to Only posts in a taxonomy and Terms (slugs or IDs, comma separated). Use Colour and filter by to turn each term into a colour and a filter.
5. Choose Featured image in popups, Excerpt in popups and At most this many posts (default 500).

Field names are custom field (post meta) keys, including ACF, Meta Box, JetEngine and Pods fields.

On archive and search pages, add the Posts map (Query Loop) block inside a Query Loop, or use [matrixmap_posts map="ID"]. The map then shows only the posts listed on that page.

First, choose a routing service under MatrixMap → Settings → Directions (see Directions on the map).

Route through the places

1. In a map’s Places tab, turn on Draw the road route between the places. Places are joined in list order, which suits tours, itineraries, delivery runs and events.
2. Pick the Travel mode, and optionally Back to the first place (round trip).
3. Set Line colour and Line width, then Show the total distance and time and Show turn-by-turn directions.
4. Save the map. The route is worked out once when you save, so visitors never wait. It is worked out again when you change the places and save.

Elevation profile

In the Shapes tab, turn on Show an elevation profile for GPX tracks. Below the map, visitors see distance, ascent, descent and a chart. Pointing at the chart shows that spot on the map. This needs a GPX file with elevation data, for example from Strava, Komoot or Garmin.

Both options are in a map’s Style tab and need the vector map engine.

• Heatmap → Show places as a heatmap shows where places are concentrated. Set Radius (px) (default 25), Intensity and Show markers from zoom (default 12). From that zoom level, individual markers appear.
• Globe view → Show the map as a 3D globe shows the world as a globe when zoomed out and flattens it as visitors zoom in. Spin slowly until the visitor touches it is optional. The globe never spins for visitors who prefer reduced motion. It shows on the published map.

Locations are stored once and used everywhere: in store locators, on maps and, with Pro, on location pages. Go to MatrixMap → Locations and click Add New.

1. Enter the location name, for example “Downtown Store”.
2. Under Location details, fill in Street address, City, State / region, Postcode and Country, then click Find on map. Drag the pin or click the map to fine-tune the position.
3. Add Phone, Email, Website and optionally a Marker colour (or Use the category colour).
4. Under Extra details, click Add a detail for anything else visitors should know, for example “Parking – Free” or “Languages – English, Spanish”. Details show in popups and locator results, and can become locator filters.
5. Add a Description, a featured image and location categories, then publish.

The Locations list has a Status column that shows On the map or Needs an address. Manage categories under MatrixMap → Categories.

Your reference ID is optional. Imports use it to recognise a location again.

The Opening hours box of a location sets weekly hours:

• For each day, enter Opens and Closes. A day can have more than one shift, and shifts may run past midnight. Tick 24 hours for all-day opening. Use Copy to next day to save typing.
• Leave every day empty if you don’t want to show hours.
• Holidays and special hours: click Add a date, then choose Closed all day or enter special hours, with a note such as “Christmas”. Special dates override the weekly hours.
• Temporarily closed: set Closed until (inclusive) for renovations or seasonal closures.
• Time zone: the default is Automatic, worked out from where the location is. Visitors see “Open now” or “Opens at …” in the location’s own time zone.

In a CSV import, hours can be written as Mon-Fri 09:00-17:00; Sat 10:00-14:00.

1. Add your locations first, or import them (see Import locations from a spreadsheet).
2. Go to MatrixMap → Add New Map, choose Store locator and click Create map.
3. Set up the Locator tab using the table below.
4. Publish, then add the locator to a page with the Store Locator block or its shortcode.

Results show the distance, the opening status, a call button and directions in Google Maps, Apple Maps or Waze.

MatrixMap Pro adds result templates, an “Open now only” filter, directions drawn on the map, messages to locations and links to location pages. See the Pro sections below.

The Store Search block, or [matrixmap_search], is a small search box for your header or home page. It sends visitors to your locator page with their search, or with “Use my location”.

• Set the locator page in the block, or with page="ID" in the shortcode. If you leave it empty, MatrixMap finds the page that shows your store locator.
• You can change the label, placeholder and button text, and hide the “Use my location” button.

You can also link straight to a locator page with these URL parameters:

“Open now” filter

Go to MatrixMap → Settings → Locator extras and turn on Add an “Open now only” checkbox to store locators (on by default). The filter runs on the server. It uses each location’s own time zone, holidays and overnight hours, so visitors get the nearest locations that are open, even when the closest ones are closed.

Result templates

In a store locator’s Locator tab, under Results look, choose Show results as: List (default), Cards with photos, List with photos or Compact (one line each). Photos are each location’s featured image. Use Show photos and Show “Open now” / “Closed” to switch those parts on or off.

Directions can show the route and turn-by-turn steps inside your own map, instead of sending visitors to another app. Locator results get a Route button, and map popups get directions on the map.

1. Go to MatrixMap → Settings → Directions.
2. Choose the Routing service:
   • Off: directions open in Google or Apple Maps. This is the default.
   • OSRM open servers: no key, for light use only.
   • OpenRouteService (free key), GraphHopper, Mapbox or Google Routes API (all need a key).
3. Enter the API key for a keyed service. For Google, the key saved under Providers & API keys is used if this is empty; enable the Routes API for it. Keys are never shown to visitors or included in settings exports.
4. Tick the Travel modes visitors can switch between: Drive, Walk and Cycle.

Route requests go through your site, and results are cached. Each visitor is limited to 60 route requests an hour. The whole site is limited to 600 an hour with OSRM, or 1,000 an hour with other services.

Every location can get its own public page with a map, address, contact details, opening hours, extra details and directions. Search engines see it as LocalBusiness structured data.

1. Go to MatrixMap → Settings → Location pages.
2. Turn on Publish a page for each location.
3. Set the Address, which is the first part of every page address (default locations, giving /locations/location-name/). Permalinks are refreshed for you.
4. Choose the Business type used in the structured data, for example Store, Restaurant, Car dealer, Dentist, Hotel or Local business (general).

The pages are added to the WordPress sitemap automatically. Locator results and map popups link to them. The structured data includes the address, coordinates, opening hours and special dates.

This adds a “Send a message” button to map popups, locator results and location pages.

1. Go to MatrixMap → Settings → Messages and turn on Let visitors send a message to a location.
2. Send messages to: The location’s own email (or the address below), or Always the address below.
3. Central address is used when a location has no email. It defaults to the site admin email.
4. Send a copy to is optional, for example your head office.

Messages are emailed with the visitor as the reply-to, so you answer from your inbox. They are not stored on your site. Spam is filtered with a hidden field, a minimum fill time and a limit per visitor, with no CAPTCHA and no third party.

Analytics is off until you switch it on.

1. Go to MatrixMap → Settings → Analytics and turn on Collect analytics. You can also click Turn on analytics on the MatrixMap → Analytics screen.
2. Keep data for between 30 days and 3 years (default 365 days).

MatrixMap → Analytics shows totals for 7 days, 30 days, 90 days or 12 months:

• Searches and Nothing nearby (searches with no result).
• Directions, calls, website clicks, page views and messages, with a chart per day.
• Top locations by directions, calls, clicks, views and messages.
• Where people look but you have no location: a map of areas where searches found nothing nearby.

Use Export CSV to download the data, or Delete all data to start again. Only anonymous daily totals are kept. There are no cookies and no IP addresses, and search areas are rounded to about 11 km.

Visitors, members or dealers can add their own location. Every submission waits for your review unless you trust the person.

1. Go to MatrixMap → Settings → Submissions and turn on Accept location submissions.
2. Who can submit: Anyone or Only logged-in users.
3. Review: Review every submission, or Publish right away for users who can publish posts.
4. Category for submissions is added to every submitted location. Category for dealers is used by the dealer sign-up form, so dealers can have their own locator.
5. Photos allows a JPEG, PNG or WebP photo of up to 2 MB. Editing lets logged-in users update their own locations; changes go back to review when reviews are on.
6. Notify sets who hears about new submissions (default: the site admin email).
7. Add the Submit a location block to a page, or [matrixmap_submit]. For dealer sign-up, use [matrixmap_submit type="dealer"], or set the block to dealer sign-up.

Review submissions under MatrixMap → Locations, in the Pending view. When you publish a submission, the submitter gets a “now live” email. A dealer’s enquiry email is stored privately and never shown on the site.

Members see and edit their own listings with [matrixmap_my_locations].

Spam is filtered with a hidden field, a minimum fill time and limits per visitor and per site.

A “Find a dealer near you” form. The visitor enters a postcode or address and a message, and it goes to the nearest location that has an email address. The visitor sees who will answer.

1. Go to MatrixMap → Settings → Leads to dealers and turn on Send enquiries to the nearest location.
2. Only these categories: location category IDs separated by commas, for example your dealers category. Leave it empty for all locations.
3. Farthest distance in km. 0 means no limit. For anything farther away, the enquiry goes to the central address under Messages.
4. Send a copy to is optional, for example your sales team.
5. Add the Dealer enquiry block, or [matrixmap_lead], to a page.

Leads are emailed and not stored. Each lead is counted in Analytics.

With WooCommerce active, a product page can show a store finder that lists only the shops that stock that product.

1. Edit a product and open Product data → Where to buy.
2. Set Store finder to All locations sell it, Locations in these categories sell it (choose the Location categories, for example “Stockists”), or These locations sell it.
3. With hand-picked locations, set the stock at each one: In stock, Low stock, Out of stock or Does not sell it.
4. Optionally change the Tab title.

A “Where to buy” tab is added to the product page automatically. To place the finder elsewhere, use [matrixmap_where_to_buy], or [matrixmap_where_to_buy product="123"] outside the product page. Searches in this finder only return the product’s stockists.

The Nearest location block, or [matrixmap_nearest], shows each visitor the locations closest to them, with distance, opening status and directions.

• It starts from the visitor’s approximate location, from your CDN or the IP location database. It offers a “Use my exact location” button when precise location is allowed.
• Set how many locations to show (1–10), limit to some categories, and change the heading (default “Your nearest location”).

The block works with full-page caching, because the browser asks an uncached endpoint for the visitor’s location.

Geo-targeted content

The Geo content block, or [matrixmap_geo]…[/matrixmap_geo], shows or hides any content by the visitor’s country, by distance from a place, or by distance from your nearest location.

[matrixmap_geo countries="GB,IE"]Free delivery in the UK and Ireland.[/matrixmap_geo]
[matrixmap_geo near="51.5074,-0.1278" radius="25"]Visit our London showroom.[/matrixmap_geo]
[matrixmap_geo near_store="10"]There is a store less than 10 km from you.[/matrixmap_geo]
[matrixmap_geo mode="hide" countries="US"]Prices include VAT.[/matrixmap_geo]

It works with page caching: the page carries the rule, and the browser checks it against the visitor’s location. “Show” content stays hidden until it matches. “Hide” content stays visible unless it matches.

If the visitor’s country can’t be worked out, the content is shown. Use geo content for relevance, such as prices and contacts, and never to hide confidential information.

On hosts without a CDN location header, a local copy of the free DB-IP Lite database answers “where is this visitor?” on your own server. It powers “near you” locators, the Nearest location block and geo content. Visitors’ IP addresses are never sent anywhere and never stored.

1. Go to MatrixMap → Settings → IP location database.
2. Choose the Database edition: City (country, city and coordinates, about 130 MB on disk, recommended) or Country (about 8 MB).
3. Leave Update automatically every month on, then click Download and install.

The How this site sees you right now card shows the country, city, position and source detected for you, as a quick check. Use Update now or Remove at any time.

The database file is kept in wp-content/uploads/matrixmap-pro/ipdb by default. Data: IP Geolocation by DB-IP (CC BY 4.0).

Region maps show the world, a continent, a country or its regions as clickable shapes. Your site draws them itself, so they contact no outside service and need no consent.

302 maps are included:

• The world by countries or by continents, and United States by states.
• The counties of every US state.
• The states, provinces or regions of more than 200 countries.
• Detailed maps: France (departments), Italy and Spain (provinces), United Kingdom (local authorities), Germany, India and New Zealand (districts), Australia (local government areas), Canada (economic regions), Philippines (provinces) and the municipalities of each Mexican state.

In the Regions tab, open Map and type to search the list.

MatrixMap Pro adds combined maps and your own maps from SVG or GeoJSON. See Custom and combined maps.

Click a region on the preview, or pick it under Find a region, and set:

• Value: used to colour the region when “Colour by value” is on, and shown in its tooltip.
• Colour: overrides “Colour by value” for this region.
• Name to show, Details and a Link (optionally Open the link in a new tab).
• Group: regions with the same group name light up together and show the group name, for example a sales territory.
• Hide this region: hidden regions are drawn faintly and can’t be clicked.

Tick several regions to use Edit selected regions. You can colour them, set a value or link, hide, show or clear them all at once.

Import from a spreadsheet

Copy two or three columns from Excel or Google Sheets and paste them under Import from a spreadsheet: the region code or name, the value, and an optional link. Then click Import. Common names such as “USA”, “Ivory Coast” and “Los Angeles County” are recognised. MatrixMap reports how many rows were imported and how many were not matched.

In the Style tab, turn on Colour regions by their value to make a data map, where higher values get stronger colours.

• Palette: ten palettes, including Viridis and Cividis, which are colour-blind safe.
• Show values as: Coloured regions or Bubbles sized by value.
• Scale: Equal ranges, Equal counts (quantiles) or Smooth gradient, with a number of Colour steps.
• Before values and After values add units such as “$” or “%”.
• Show a legend with a Legend title and a Legend position (a corner, or Below the map).

Under Colours, set the colours for regions, hover and keyboard focus, borders, the background (sea) and regions without data.

• When a region is clicked: Open its link (if it has one), Show its details below the map or Show its details in a pop-up. Details are the name, value, text and link you add to a region.
• Tooltips: On hover, On click or Off. With “On click”, the first click shows the tooltip and a second click opens the region’s link.
• Regions without data: Show them, Fade them, or Hide them (the map frames the rest). A region has data when it has a value, colour, name, text, link or group.
• Region names on the map and Zoom buttons.
• Find a region → Next to the map: Nothing, A search box or A list of regions with data. Choosing a region zooms to it and shows its details.
• Selected when the page opens: preselect a region. A link can also pick one by adding ?mm_region=CODE to the page address.
• “Show data as a table” link: an accessible alternative for screen reader users. It is recommended to leave this on.

In the Markers tab, add places on top of the regions in the same way as on a map.

• Marker style → Shape: Round dots or Map pins. Set a Size (pixels) and choose Show place names next to markers.
• Lines between markers → Connect the markers joins them in list order, which suits routes, flights or supply chains. Choose a Line style (Curved or Straight), Colour, Thickness, Dashed and Animated flow. Animation is turned off for visitors who prefer reduced motion.

Starting view → Zoom in on frames chosen regions, for example only Europe on the world map. Leave it empty to show the whole map. Zoom level 0 fits the chosen regions. Deepest zoom visitors can reach limits zooming.

A region, or a marker on a region map, can open content in a window on top of the page.

1. Click the region, or the marker, in the builder.
2. Under When clicked, open, choose A picture gallery (Choose pictures), A video (a YouTube or Vimeo link, or an .mp4 or .webm file), A page or post of this site, or Another web page.

YouTube plays in privacy-enhanced mode, and videos load only when a visitor opens them. Some websites refuse to be shown inside other sites. For those, use a normal link instead.

In a region map’s Settings tab, under Drill down, turn on Drill down into countries. On the world map, clicking a country that has a map of its states or provinces opens that map, with a button back to the world. On a country map, clicking a state that has a more detailed map, such as US counties or Mexican municipalities, opens it.

Also filter a store locator on the same page makes a click on a country show only that country’s locations in the locator.

Combined maps

Pro adds two maps to the region map list: World with states and provinces and North America (states and provinces).

Your own maps from SVG or GeoJSON

Turn a floor plan, campus, shopping centre, venue, sales territories or school districts into an interactive region map.

1. Go to MatrixMap → Import & Tools → Custom maps.
2. Choose an SVG or GeoJSON file. In an SVG, give shapes an id or title in your drawing program (Illustrator, Inkscape or Figma); those become the region names. A picture inside the SVG is kept as the background. In GeoJSON, polygons need a name property, and optionally a code.
3. Check the preview, enter a Map name and click Save map.
4. In any region map, pick it under Your maps.

The SVG itself is never stored or shown, so scripts inside it can’t reach visitors. Places with coordinates can be added to GeoJSON maps. If you delete a custom map, region maps that use it show a message instead.

In a region map’s Regions tab, under Regions from your content, set Fill regions from to one of these:

• Categories or tags named after regions: each term whose name matches a region, such as “Texas” or “France”, links to its archive. The value is its number of posts. Choose the Taxonomy.
• Posts with a region field: each post names its region in a custom field or ACF field. Several regions can be separated by commas. Choose the Post type and the Field with the region. The value is the number of posts, or the total of a Number field to add up. The details list the posts.

Anything you set by hand in the editor always wins.

From a Google Sheet or feed

1. In Google Sheets, choose Share → Anyone with the link can view.
2. In the region map’s Regions tab, under Data from a Google Sheet or feed, paste the Sheet, CSV or JSON link.
3. Use a column or key called region (name or code) and value, and optionally label, link, colour and details.
4. Choose Check for changes: every hour, twice a day, once a day, or only when you update the map.
5. Save the map. It reports how many regions were read and which rows were not found on the map. Click Read the sheet now to refresh it by hand.

Pages never wait for the sheet, because it is refreshed in the background. If the sheet can’t be read, the last good copy is kept.

Go to MatrixMap → Settings → Maps & style. These are defaults for new maps. Each map can override them in the builder. Only administrators, or roles with the manage_matrixmap capability, can change settings.

Maps use your theme’s fonts.

Keys are only needed for Google Maps and premium styles. Go to MatrixMap → Settings → Providers & API keys.

Google Maps

1. Open the Google Maps Platform console and create a project. A billing account is required, even for free usage.
2. Enable Maps JavaScript API. For address search with Google, also enable Geocoding API.
3. Create an API key and restrict it to your website (HTTP referrers, for example https://example.com/*) and to those APIs.
4. Paste it into API key and click Test key.

Geocoding key is an optional server-only key for Google address search. It is never sent to browsers. Restrict it to the Geocoding API and your server’s IP address. Map ID is optional; create one under Map Management in the Cloud Console to style Google maps.

Premium styles

Add keys for MapTiler (streets, outdoor, satellite and dataviz styles, plus address search), Thunderforest (outdoor, cycling and transport tiles) and Mapbox.

A saved key is never shown again. Leave the field empty to keep it, or tick Remove. Keys are never included in settings exports.

Address search turns addresses and postcodes into positions: in the map builder, for locations and in store locators. Go to MatrixMap → Settings → Address search.

• Service: OpenStreetMap Nominatim (free, no key, fair-use limits; the default), Photon by Komoot (free, no key), MapTiler (API key) or Google Geocoding (API key).
• Your countries: two-letter country codes, for example US, CA. Searches stay in these countries, so a postcode or town name finds the right place. Leave it empty for worldwide search.

Results are cached, so each address is looked up only once. To protect the free services, each visitor can make 40 address searches every 10 minutes, and the site sends at most 600 uncached searches every 10 minutes.

Visitor location

Store locators can start near the visitor, and searches can prefer local results, without a permission prompt. Go to MatrixMap → Settings → Visitor location and set Where it comes from:

• Use the country/city my CDN or host reports (default). This works behind Cloudflare, CloudFront, Vercel, Fastly, Akamai and many hosts. Nothing is sent to a third party.
• Off.

On hosts without a location header, MatrixMap Pro adds a local database. See IP location database.

Map tiles come from an outside server, which sees the visitor’s IP address. Go to MatrixMap → Settings → Privacy & consent.

• Load maps:
  • After consent when a consent plugin is installed (recommended, the default). This works with WP Consent API, Complianz, Cookiebot, CookieYes, Borlabs and iubenda. With no consent plugin installed, maps load immediately.
  • Only after the visitor clicks “Load map”.
  • Immediately.
• Consent category: the category your consent plugin uses for maps. Choose Marketing (default), Preferences, Statistics or Functional.

A waiting map shows a short placeholder with a button that loads that one map. Region maps never need consent.

Performance

• Lazy loading → Load a map only when it scrolls into view (on by default).
• Scrolling over maps: Page scrolls; two fingers or Ctrl + scroll move the map (default), or The map captures scrolling and dragging.

Nothing loads on pages without a map. On pages with one, a loader of about 2 KB fetches only what that map needs. MatrixMap’s scripts are excluded from “delay JavaScript” and script combining in popular optimisation plugins.

Advanced

When the plugin is deleted → Also delete all maps, locations and settings is off by default. See Uninstalling and your data before you switch it on.

1. Go to MatrixMap → Import & Tools → Import locations. Click Download a sample file to see the expected columns.
2. Upload a CSV file (UTF-8, separated by commas, semicolons or tabs).
3. Match each column to a field: Name, Street address, City, State / region, Postcode, Country, Full address (one field), Latitude, Longitude, Phone, Email, Website, Description, Category (comma separated), Reference ID, Opening hours, or Extra detail. For an extra detail, the column name becomes the label. Choose — Skip — to ignore a column.
4. Tick Update existing locations with the same reference ID, or the same name and address to update rather than duplicate.
5. Start the import and follow the progress. The report shows created, updated and failed rows.

Rows without coordinates are placed from their address. Very large files take a while with the free OpenStreetMap search, at about one address per second.

With MatrixMap Pro you can also import from the command line (wp matrixmap import), or keep locations in sync with a sheet. See Data sync.

Go to MatrixMap → Import & Tools → Export.

• Locations: download every published location as CSV (spreadsheet) or GeoJSON, including hours, categories and extra details.
• Maps: tick maps and click Export selected maps. This copies maps to another site or keeps a backup. On the other site, use Import maps; imported maps arrive as drafts. Pictures from the Media Library are not included. You can also use the Export row action in the Maps list.
• Settings: Export settings and Import settings move settings between sites, for example from staging to live. API keys are not included. With Pro, its settings are included too, except the routing key and the licence.

1. Go to MatrixMap → Import & Tools → Switch from another plugin. MatrixMap lists the data it finds from:
   • Maps: WP Go Maps, MapPress, WP Maps (WP Google Map Plugin) and Interactive Geo Maps (MapGeo).
   • Stores: WP Store Locator and Agile Store Locator, with categories and opening hours.
2. Click Import. The other plugin’s data is only read, never changed. Clicking Import again updates the same maps instead of making copies.
3. Check the new maps under MatrixMap → Maps, then deactivate the old plugin. Its shortcodes and blocks on your pages now show the MatrixMap version, so you don’t have to edit pages.

Maps kept inside pages, such as Leaflet Map shortcodes and WP Map Block blocks, are shown by MatrixMap once the original plugin is deactivated. Interactive Geo Maps region maps keep their region codes, so values, colours, tooltips and links carry over.

Go to MatrixMap → Import & Tools → Maintenance.

• Location index → Rebuild index: use this if the store locator misses locations after a direct database import.
• Geocoding cache → Clear cache: use this if an address moved. The card shows how many addresses are cached.
• System: the installed versions, and a link to Site Health.

MatrixMap adds checks to Tools → Site Health: whether its database tables exist (they are recreated if missing), and whether the map style can be reached from your server. Its details are included in the Site Health info, ready to copy for support.

Keep your locations in step with a Google Sheet, a CSV file or a JSON or GeoJSON feed. Edit the sheet and the map updates by itself.

1. Go to MatrixMap → Import & Tools → Data sync and click Add a data source.
2. Paste the Sheet or file address. For a Google Sheet, share it as “Anyone with the link can view”, or use File → Share → Publish to web → CSV.
3. Give it a Name and choose Sync: Every hour, Twice a day, Once a day, or Only when I click “Sync now”.
4. Optionally choose a Category for rows without one. Under Options, tick Unpublish locations that are no longer in the source and Email the site admin when a sync has problems.
5. Click Save and preview. Check how each column will be imported and how many rows are new, changed or unchanged. Nothing is imported until you sync.
6. Click Sync now. It runs in the background, and Recent runs shows the result.

Rows are matched by a Reference ID column, or by name and address, so they are updated in place and never duplicated. Only changed rows are written and geocoded. Removed rows become drafts and are never deleted.

As a safety check, if a run finds fewer than half as many rows as last time, nothing is unpublished. Check the source.

Removing a source keeps its locations.

The blocks show a live preview in the editor.

Classic widget and Elementor

• Classic widget: under Appearance → Widgets, add the MatrixMap widget, choose a map and set a title and height.
• Elementor: drag the MatrixMap widget onto the page, then under Map use Choose a map and set the Height.
• Any other builder: paste the map’s shortcode into a shortcode or text element.

MatrixMap Pro adds native elements for Bricks, Divi and WPBakery. See Bricks, Divi and WPBakery.

[matrixmap]: a saved map

[matrixmap_locator]: a store locator

[matrixmap_region]: a region map

Use a saved region map (id) for colours and data.

[matrixmap_search]: a Store Search box

The map builder shows each map’s shortcode in the top bar, and the Maps list shows it too.

If Pro is deactivated, these shortcodes print nothing for visitors, and a short note for people who can edit maps. Raw shortcode text never appears on live pages.

With Pro, each of these builders gets a MatrixMap element when the builder is active:

• Bricks: a MatrixMap element.
• Divi: a MatrixMap module for Divi 4, which also works in Divi 5 as a backwards-compatible module.
• WPBakery: a MatrixMap element ([matrixmap_vc map="ID" height=""]).

Each element inserts any saved map, store locator or region map, chosen from a list, with an optional height.

All hooks use the matrixmap_ prefix.

• matrixmap:ready: fired on the map element (it bubbles). event.detail.view is the map view.
• matrixmap:region-activate (cancelable): a region or marker on a region map was clicked. detail has view, region and config. Call preventDefault() to handle the click yourself.
• matrixmap:locator: a store locator is ready. detail has filters, params, cards, origin() and refresh() for custom filters and result cards.
• window.MatrixMap.popupActions: an array of functions (actions, marker, ctx) that add buttons to map popups.
• In the editor, the matrixmap.builder.sections, matrixmap.builder.regionFields and matrixmap.builder.markerFields filters (from wp.hooks) add panels and fields to the map builder.

document.addEventListener( 'matrixmap:region-activate', function ( e ) {
	if ( e.detail.region === 'FR' ) {
		e.preventDefault();
		// Your own handling.
	}
} );

The namespace is /wp-json/matrixmap/v1/.

MatrixMap Pro adds routes under /wp-json/matrixmap-pro/v1/: /nearest, /route, /maps/{id}/route, /maps/{id}/sheet, /content/{id}, /contact, /lead, /submit and /event. They serve the Pro front-end features.

wp matrixmap import stores.csv --dry-run
wp matrixmap export --format=geojson --file=locations.geojson

• Waiting for consent? Accept cookies in your consent banner, or check MatrixMap → Settings → Privacy & consent and the map’s own Load this map setting.
• Optimisation plugins that combine or delay JavaScript can stop maps loading. MatrixMap excludes itself in popular optimisers. If yours isn’t covered, exclude scripts whose path contains /geo-maps/build/ and clear the cache.
• Is the map published? Draft maps don’t show to visitors.
• Check the Dashboard’s health warnings, Tools → Site Health, and your browser console for a message that starts with [MatrixMap].

The tile or style server may be blocked by a firewall or an ad blocker, or a keyed provider may have rejected the key. Try another style under MatrixMap → Settings → Maps & style. The Site Health check “MatrixMap map style is reachable” tests the style from your server. The map shows a message when tiles keep failing.

The OpenStreetMap standard tile server is for light use only. For busy sites, choose vector maps or a keyed provider.

Google Maps shows an error or “For development purposes only”

The Google key is missing, restricted to other sites, or billing isn’t enabled in Google Cloud. Click Test key under MatrixMap → Settings → Providers & API keys for Google’s own explanation. Make sure Maps JavaScript API is enabled for the key.

If Google Maps is the default engine but no key is saved, maps fall back to vector maps. The Dashboard warns you when this happens.

• Add the postcode and country, or type the coordinates as latitude, longitude.
• Set Your countries under MatrixMap → Settings → Address search so that short queries find local places.
• The free OpenStreetMap search allows about one lookup per second. Heavy imports should use a keyed service such as MapTiler or Google. The Dashboard suggests this when you have many locations.
• If an address changed, clear the cache under MatrixMap → Import & Tools → Maintenance.
• Visitors who search many times in a row may see “Too many searches. Please wait a minute and try again.” This is the rate limit that protects the free services.

• Only published locations with coordinates are searched. In MatrixMap → Locations, look for “Needs an address”, open the location and click Find on map.
• Check the locator’s Only these categories, radius choices and Limit search to countries.
• After a direct database import, rebuild the index under MatrixMap → Import & Tools → Maintenance.

Emails from forms don’t arrive

Messages, submissions and leads are sent with WordPress email. Many hosts need an SMTP plugin to deliver email reliably. Also check the addresses under MatrixMap → Settings → Messages, Submissions and Leads to dealers. When a message or lead can’t be emailed, Pro shows a notice in the admin, so the enquiry is not lost unnoticed.

Directions say the routing service is busy

The open OSRM servers are for light use. For a busy site, choose OpenRouteService, GraphHopper, Mapbox or Google with a key under MatrixMap → Settings → Directions. Routes are cached, so repeated requests don’t count again. Route requests are also limited per visitor and per site each hour. Developers can change the limits with matrixmap_pro_route_limits.

A Google Sheet can’t be read

If Google returns a sign-in page, the sheet is private. Share it as “Anyone with the link can view”, or publish it to the web as CSV (File → Share → Publish to web). A link that opens an ordinary web page, rather than CSV or JSON data, is refused. Region maps keep the last good copy of the data, and data sync logs each problem under Recent runs.

Do I need an API key?

No. Vector maps (the default), classic OpenStreetMap tiles, region maps and the OpenStreetMap address search all work without a key. Google Maps and some tile and search providers need one.

What is the difference between Free and Pro?

The free plugin is complete: maps, store locators, region maps with data, imports and exports, blocks and the Elementor widget, with no limits on maps or locations. Pro adds directions on the map, submissions and dealer leads, analytics, SEO location pages, data sync, drilldown, click actions, custom maps, geo-targeted content, WooCommerce and page-builder integrations, and WP-CLI. The MatrixMap → Free vs Pro screen compares them.

What happens if my Pro licence expires?

Pro keeps working, and so do your maps. The licence brings one-click updates and support.

Does it work with WPML or Polylang?

MatrixMap ships a wpml-config.xml, so maps and locations can be translated.

Is MatrixMap accessible?

Markers are real buttons, popups work with the keyboard, maps can show a list of places, and region maps have a “Show data as a table” link for screen reader users. Animations respect the reduced motion setting.

A user can’t edit maps or settings

Maps and locations use their own capabilities (edit_matrixmaps and related). Administrators and Editors have them by default. Settings and Import & Tools need manage_matrixmap, which only Administrators have by default. A role editor plugin can grant these capabilities to other roles.

What MatrixMap stores

• Your maps and locations (as WordPress posts), their settings and location categories.
• A location index table and an address search cache table, so addresses are looked up only once.
• Plugin settings, including any API keys you enter.
• The free plugin stores nothing about visitors and sets no cookies.

Outside services

A map that shows tiles makes the visitor’s browser download them from the provider you chose: OpenFreeMap by default, or OpenStreetMap, Google or another provider. That provider receives the visitor’s IP address and browser details, as with any web request. This is why maps can wait for consent. Address searches are made by your server to the search service you chose. Region maps use no outside service.

With MatrixMap Pro

• Analytics is off until you switch it on. It keeps anonymous daily totals only, with no cookies or IP addresses.
• Messages and leads are emailed and not stored on the site.
• Submissions are stored as pending locations with the submitter’s name and email, used for the approval email.
• Directions send the start and end points to the routing service you chose, through your server. Keys stay on the server.
• IP location database: the database is downloaded to your server, so visitors’ IP addresses are looked up locally.
• Video click actions load YouTube (privacy-enhanced mode) or Vimeo only when the visitor opens the video.
• Licence checks send the licence key, the site address and the plugin version to the licence server.

Uninstalling

Deactivating MatrixMap never deletes anything. Deleting the plugin only stops its scheduled task and keeps your maps, locations and settings, so reinstalling brings everything back.

Only when Also delete all maps, locations and settings is on (MatrixMap → Settings → Advanced) does deleting the plugin remove all maps, locations and location categories, its settings, capabilities, caches and its own database tables.

MatrixMap Pro follows the same setting for its analytics, data sources, custom maps and per-map and per-product settings. Its licence, scheduled tasks and downloaded IP database are always removed when Pro is deleted.

Deleting data can’t be undone. Export your maps and locations first under MatrixMap → Import & Tools → Export.