Description
Mapsemble turns a list of places into a map people can search: a store locator, a dealer or member directory, a holiday-home finder. Visitors search by town or postcode, filter, and see the results as cards beside the map, following along as they pan and zoom.
Free for up to 150 locations per map, with unlimited map views. There is no per-view pricing on any plan, and you need no Google Maps API key. 500 address lookups are included for the account’s lifetime; rows with coordinates, or addresses already looked up, don’t count. Free maps carry a small Mapsemble logo; the Pro plan lets you hide it.
A store locator in three steps
- Bring your locations. Go to Mapsemble → Add new map and choose how: type them in, upload a spreadsheet, link a Google Sheet, or describe the map you want.
- Check your map. It appears right there in WordPress, with a short report: how many locations are on it, and a field to correct any address that could not be found.
- Put it on a page. One click creates a draft page holding the map. Publish it like any page.
Add new map is where every way in leads: the notice after you activate the plugin, the “Add new map” button on Mapsemble → Maps, and the Mapsemble Map block’s “Create a store locator” button. The “Store locator” block pattern puts a heading, a line of text and a wide map on any page.
Four ways to bring your locations
- Type or paste them. A small table for up to 150 locations: a name and an address each, with a phone number and website if you like. Rows copied from a spreadsheet fill it.
- Upload a spreadsheet. CSV, TSV or Excel (.xlsx, .xlsm), up to 10 MB, or less if your host’s upload limit is lower. Mapsemble suggests what each column holds (name, address, phone…); you check it, and the map is built.
- Link a Google Sheet. Share the sheet as “Anyone with the link” can view and paste its link. The map follows the sheet: press Sync now on Mapsemble whenever it changes, or let the Pro plan sync it every 15 minutes.
- Describe your map. Not a store locator? Say in a sentence or two what the places are and where. Mapsemble’s AI designs the fields, filters, cards and style, and adds a few example locations so you see it working; they disappear once your own locations arrive.
Importing a spreadsheet or a Google Sheet is free on every plan: no paid add-on.
Already in WordPress? “Map your posts” on the same screen maps a post type instead (Pro, on a public site; see below).
Your account, when you ask for your map
You don’t need an account to look around. The first time you press a button that sends your locations (“Put them on a map”, “Continue” or “Build my map”), a small Mapsemble window opens: sign in, or create a free account with Google or your email. A new account connects the site without a second click; the window closes itself and the screen carries on where you left it. Nothing is sent to Mapsemble before you press that button.
Why Mapsemble
- List and map together. Results appear as cards beside the map and stay in step with it as visitors pan, zoom and filter, with a layout of its own on phones.
- Search and filters. Location search, plus filters on any field: categories, numbers, dates.
- Your design. Markers, clustering, card layouts and colours are set in the Mapsemble map builder, without code.
- Fast with large datasets. The map loads only what is in view and the list pages through the rest, so thousands of locations stay quick.
- Free to start. Up to 150 locations per map for free. The Pro plan removes the cap, lets you hide the logo, and can feed a map straight from your WordPress posts.
Already have maps?
Add the Mapsemble Map block to a page and pick one of your maps in the canvas; it previews live. Before you connect anything, the block shows a working sample map. Mapsemble → Maps lists your account’s maps: “Add locations” brings in more, typed or from a spreadsheet or sheet, and “Edit locations” leads to the Mapsemble location editor, which opens in a new tab with the map beside it.
Or map your WordPress posts (Pro)
Under Mapsemble → Built from this site, make a post type the map’s data: give your posts a location (find an address, enter coordinates, or use an ACF Google Map field) and the map shows them, with cards rendered from your own templates. This needs a site Mapsemble can reach from the internet, and the Pro plan; nothing is blocked before then, but visitors see an upgrade notice over the map until the account is upgraded.
For developers
Placing a map without the block. Every map embeds by its Mapsemble map id:
- Shortcode:
[mapsemble map="0198…" height="60vh" scroll_capture="mobile"]for any map (ormap="sample"),[mapsemble id="123"]for a map built from this site (its id is on the Built from this site list, ready to copy). This is also how a map goes into the classic editor, a Text widget or a page builder. - Template functions:
mapsemble_embed( '0198…' )/the_mapsemble_embed( 'sample' )for any map,mapsemble_map( 123 )/the_mapsemble_map( 123 )for a map built from this site.
A map built from this site serves from this site however it is embedded, by its map id too: “fed by WordPress” is a property of the map, not of where you embed it.
height and the two offsets (`scroll_offset_top`, `scroll_offset_bottom`) take a CSS length (`50vh`, `480px`, `2rem`). `scroll_capture` is `none` or `mobile` and turns the map into a sticky section: scroll gestures over it move the card list instead of the page, and the map sticks at the top offset, which is how you clear a fixed site header. While the map fills the visible screen, both offsets are also taken off its height. `fill_viewport="false"` makes `height` exact instead of a minimum. `filters` seeds the map's filters on load, as a JSON object of filter slug to value; quote it with single quotes: `[mapsemble id="123" filters='{"category":"parks"}']`. An unreadable value is ignored. In the block these live in the sidebar; in `mapsemble_map()`, pass `filters` as a native array.
Shaping a site-fed map. On the map’s own edit screen, with no reindexing:
- Always-on filters restrict which posts appear, by taxonomy term or custom field, so two maps on one post type can show different posts.
- Visitor filters bind the filter widgets configured on Mapsemble to your taxonomies and custom fields; option pickers are fed from your content.
- Sort options bind the map’s sort choices to publication date, title, a custom field, or entropy (an even geographic spread).
- Marker style properties put taxonomy terms or custom field values on every map feature, for Mapsemble’s marker-style rules.
The feed is a standard WordPress meta query and is comfortable up to roughly ten thousand geo-tagged posts; beyond that, use a persistent object cache. The entropy sort needs MySQL 8 or MariaDB 10.2 for its window function, and degrades to a stable per-map random order on older databases. The filter option pickers group over meta values, capped at ten options per lookup.
Hooks. Filters: mapsemble_card_html, mapsemble_card_template, mapsemble_card_css_urls, mapsemble_card_data (the card), mapsemble_location_sources, mapsemble_post_coordinates (where coordinates come from), mapsemble_features_query_args, mapsemble_feature_properties (the feed), mapsemble_widget_settings, mapsemble_widget_translations (the widget), mapsemble_feed_cache_ttl (the feed cache), mapsemble_app_base, mapsemble_remote_base_url, mapsemble_sample_app_base (hosts). Action: mapsemble_map_config_saved. Copy templates/card.php into your theme as mapsemble/card.php to change the card markup.
REST routes. Public, for site-fed maps only: mapsemble/v1/features (the GeoJSON feed), mapsemble/v1/feature (one rendered card) and mapsemble/v1/filter/options. They serve published, geo-tagged content that the map’s own conditions admit: a post excluded by an always-on filter answers 404 exactly like a missing one, and maps whose locations live in Mapsemble answer 404 on all three. Responses carry Cache-Control: public, max-age=60 and an ETag; the cache is refreshed when a served post, its terms, or the map’s settings change. For users who can edit posts: mapsemble/v1/geocode and mapsemble/v1/map-filters. For users with edit_mapsemble_map_data (Add new map): mapsemble/v1/onboarding/*.
Constants. MAPSEMBLE_CLIENT_ID / MAPSEMBLE_CLIENT_SECRET keep the credentials in wp-config.php, and the settings fields become read-only. Credentials set that way never pass through the settings form, which is what normally clears the cached access token and plan details: after changing them, call \Mapsemble\Api\Client::forget_account_caches() (or delete the mapsemble_token, mapsemble_token_failed, mapsemble_remote_maps, mapsemble_map_fields, mapsemble_feature_flags and mapsemble_backoff transients), or the plugin keeps answering for the previous account for up to fifteen minutes.
External Services
This plugin connects to the Mapsemble service (https://app.mapsemble.com). Nothing is sent when the plugin is activated; each exchange below follows something you do. The sample map loads from app.mapsemble.com like any other map, connected or not.
- The map widget. Pages where you embed a map, and the live previews in the block editor and on Add new map, load the Mapsemble widget (widget.js) from app.mapsemble.com. Visitors’ browsers request the map’s configuration from the Mapsemble service; their IP address and the map id are visible to it, as with any embedded map service. A map whose owner set a Google or Mapbox basemap key loads its tiles from that provider in the visitor’s browser; otherwise tiles come from Mapsemble. What visitors type in a map’s location search is sent to Mapsemble, which looks it up with Mapbox. Mapbox terms: https://www.mapbox.com/legal/tos — Mapbox privacy policy: https://www.mapbox.com/legal/privacy
Mapsemble counts a published map’s views and notes which site it is shown on, for the map’s statistics; the editor previews say they are previews, and count as neither. - Connecting. “Sign in or create a free account” (on Add new map, or under Mapsemble → Settings) opens app.mapsemble.com in a small window, carrying a one-time random code and this site’s address. You sign in or sign up there, with Google or your email, and approve (a new account is approved by signing up); the plugin then collects the API credentials over a server-to-server request, so they never pass through your browser.
- Your account’s maps. From the admin area the plugin authenticates with your API credentials to list your maps, read a map’s fields, filters and sort options, read your plan’s limits (
/api/v1/me), create maps, and tell Mapsemble where each map’s data comes from. Once a day, after you connect, it reads Mapsemble’s list of API endpoints (/api/v1) to see which ways of adding locations your Mapsemble offers. - Building a map. When you press “Put them on a map” or “Build my map” on Add new map, this site’s server asks Mapsemble to create the map, with its name, and with your description when you described it. Every address you send, typed or imported, is looked up by Mapsemble with Google’s Geocoding API. Google Maps Platform terms: https://cloud.google.com/maps-platform/terms — Google privacy policy: https://policies.google.com/privacy
- Typed rows. When you press “Put them on a map”, the names, addresses, phone numbers and websites you typed are sent from this site’s server to Mapsemble. Correcting an address in the report and pressing “Place it” sends that one address again.
- A spreadsheet. When you press “Continue”, the file you chose is sent from this site’s server to Mapsemble, which stores it with your account to import it (a file you never import is deleted). To suggest what each column holds, Mapsemble sends the column names and up to five sample values per column to Google Gemini. When you then press “Build my map”, the rows are imported, and the new map’s cards are designed by Google Gemini from the map’s fields and three of its locations; “Add them to the map” does the same for a map built here whose cards were never designed. Google Gemini API terms: https://ai.google.dev/gemini-api/terms — Google privacy policy: https://policies.google.com/privacy
- A Google Sheet. When you press “Continue”, the link is sent to Mapsemble, which fetches the sheet from Google on its own servers: now, again when it imports, whenever you press Sync now, and every 15 minutes on the Pro plan. The column suggestion and the card design use Google Gemini as for a spreadsheet.
- A description. When you press “Build my map”, the description you typed is sent to Mapsemble, which has Google Gemini design the map’s fields, filters, cards and style, and suggest a few example locations.
- Setup steps. Mapsemble records which steps of setting up a map were completed (the connect page viewed, the connection approved, a map built and which way, its first locations added), with your Mapsemble account once you have one, to see where people get stuck and improve setup. Nothing about your site’s visitors is recorded.
- Which plugin is asking. Every request this site’s server makes to Mapsemble carries an
X-Mapsemble-Client: wordpress/<version>header naming the plugin and its version, so Mapsemble can tell which integration built a map. It says nothing about your site or its visitors. - Editing locations. For a map whose locations live in Mapsemble, “Open the location editor” under Mapsemble → Maps sends a new browser tab to app.mapsemble.com, signed in with a single-use token minted from your API credentials at the moment you click. The token is scoped to that one map, and the session it opens reaches that map’s editor and preview and no other part of your Mapsemble account. WordPress users never see the credentials.
- Address search. When an editor searches for an address in a post’s Map location box (“Find an address”), the text they typed is sent from this site’s server to the Mapsemble API (
/api/v1/geocode), and Mapsemble forwards it to Google’s Geocoding API to look up its coordinates. Visitors never trigger it. The “check it on OpenStreetMap” link next to a found address opens openstreetmap.org only when clicked. - Maps built from this site. The Mapsemble service fetches your published, geo-tagged content from public endpoints this plugin provides on your site.
Terms of service: https://www.mapsemble.com/terms — Privacy policy: https://www.mapsemble.com/privacy
Installation
- Install and activate the plugin.
- Go to Mapsemble → Add new map, bring your locations (typed, from a spreadsheet, from a Google Sheet, or described) and press the button. The first time, a small Mapsemble window opens: sign in or create a free account, and the site connects itself. (You can also connect first under Mapsemble → Settings, or paste a client ID and secret by hand there.)
- Check the map and its report, then choose “Create page”: a draft page holding the map opens in the editor. Publish it.
- Maps you already have: add the Mapsemble Map block to any page and pick one.
- To feed a map from your posts instead (Pro): Mapsemble → Built from this site → Build a map from this site.
FAQ
Is it free?
Yes, for up to 150 locations per map, with unlimited map views, and importing a spreadsheet or Google Sheet is included. 500 address lookups are included for the account’s lifetime; rows with coordinates, or addresses already looked up, don’t count. Free maps carry a small Mapsemble logo; the Pro plan lets you hide it. The Pro plan also removes the cap, syncs Google Sheets every 15 minutes and can feed a map from your WordPress posts. A spreadsheet or sheet with more rows than your plan allows puts the first 150 on the map; the rest wait on your account for an upgrade.
Do I need a Google Maps API key?
No. The map, its tiles and the address lookups all come with Mapsemble; there is nothing to set up with Google. If you would rather show Google’s or Mapbox’s own basemap, you can add that provider’s key to the map on Mapsemble, but nothing needs one.
Do I need a Mapsemble account?
Yes, a free one. You create it from inside WordPress, the first time you build a map: a small window asks you to sign in or sign up, with Google or your email, and closes itself when the site is connected. Before that, the Mapsemble Map block shows a working sample map.
Can I import a spreadsheet or a Google Sheet?
Yes. Under Mapsemble → Add new map, upload a CSV, TSV or Excel file (.xlsx, .xlsm; up to 10 MB, or less if your host’s upload limit is lower), or paste a link to a Google Sheet shared as “Anyone with the link” can view. Mapsemble suggests what each column holds (name, address, phone…); you check it, and the map is built. A map from a Google Sheet follows the sheet.
Does it work with Elementor or other page builders?
Yes. In Elementor, Divi, Beaver Builder, the classic editor or a Text widget, paste the map’s shortcode, [mapsemble map="…"]: the finished map on Add new map shows it, ready to copy. In the block editor, the Site Editor and Appearance → Widgets, use the Mapsemble Map block.
Can I map my own posts?
Yes, with the Pro plan, on a site Mapsemble can reach from the internet. Under Mapsemble → Built from this site (or “Map your posts” on Add new map), make a post type the map’s locations: give your posts a location with the Map location box, coordinates in custom fields or an ACF Google Map field, and every post becomes a card, rendered from your own templates.
Some addresses were not found. What now?
The report under your new map lists them, each with a field: correct the address and press “Place it”. Only that row is looked up again.
Can I add locations later?
Yes. On Mapsemble → Maps, “Add locations” under a map’s name brings in more, typed or from a spreadsheet or sheet. “Edit locations” changes or deletes single ones in the Mapsemble location editor.
Where does the map design come from?
From your Mapsemble account. Styling, clustering, filters, cards and layout are set in the Mapsemble map builder; “Change the design on Mapsemble” on the finished map takes you there.
Who can build maps and edit their locations?
Editors and administrators, by default. Maintaining locations is content work, so it has its own capability (edit_mapsemble_map_data) that the administrative ones deliberately do not imply. Connecting the site to Mapsemble takes an administrator (manage_mapsemble); an editor on an unconnected site is asked to fetch one.
My coordinates live in custom fields already. Can I use them?
Yes, for a map built from this site. Choose the “Custom fields (latitude/longitude meta keys)” location source and name the two meta keys; that covers Metabox.io, Pods, imported data and hand-rolled meta. An ACF Google Map field has its own named source. For computed cases, the mapsemble_post_coordinates filter remains. After switching sources, run “Reindex locations” on the map.
Can I develop against a local site?
A map whose locations live in Mapsemble works on a local site with no extra setup: nothing on the Mapsemble side ever fetches from your server. A map built from this site’s content does not, because Mapsemble has to reach your feed: expose the site through a tunnel and define MAPSEMBLE_REMOTE_BASE_URL in wp-config.php. MAPSEMBLE_APP_BASE points the plugin at another Mapsemble host, with TLS still verified; MAPSEMBLE_SSL_VERIFY set to false switches that off, for a local stack whose certificate the WordPress container does not trust only, never on a public site. The sample map always loads from app.mapsemble.com; the mapsemble_sample_app_base filter points it elsewhere.
Is the map’s interface translatable?
Yes. The widget’s interface strings (“Filters”, “Search”, “Sort by”, …) run through the plugin’s mapsemble text domain, so a translation for your language translates them. Developers can add or override strings with the mapsemble_widget_translations filter.
The map preview in the editor stays blank. Why?
The editor shows a chosen map live in a frame served by this site to a request that carries no login cookie: the block editor isolates itself in Chromium browsers, and the frame’s request goes out without cookies. Anything that turns such requests away before WordPress parses them keeps the preview out: a maintenance or “members only” plugin that redirects logged-out visitors on init, or HTTP basic auth in front of a staging site. The published page is unaffected; the map still renders there.
Screenshots






Changelog
0.6.0
- Added: Mapsemble → Add new map builds a store locator without leaving WordPress. Type or paste up to 150 locations, upload a spreadsheet (CSV, TSV or Excel), link a Google Sheet, or describe the map and let Mapsemble design it, with example locations that give way to yours. The map previews right there, with a field to correct any address that could not be found, and one click puts it on a new draft page. A “Map your posts” card leads to a map built from this site.
- Added: the first time you build a map, a small Mapsemble window asks you to sign in or create a free account; a new account connects the site without a second click, and the screen carries on by itself. Settings uses the same window (“Sign in or create a free account”).
- Added: a map built from a spreadsheet or Google Sheet is named after it and takes its fields from its columns; a column of a few repeated values becomes a choice that visitors can filter by.
- Added: “Add locations” on Mapsemble → Maps brings more locations into a map hosted on Mapsemble, typed, from a spreadsheet or from a Google Sheet, and says how many the map holds afterwards.
- Added: a “Store locator” block pattern: a heading, a line of text and a wide Mapsemble Map block.
- Changed: the Maps screen has an “Add new map” button, and an empty account is offered its first map instead of a sentence.
- Changed: with no maps to pick, the Mapsemble Map block offers “Create a store locator”, and lists the new map when you come back to the editor. Its “connect under Settings” advice only shows while the site is not connected.
- Changed: the setup notice after activation reads “Add a store locator to your site” and leads to Add new map; the connected status under Settings says what to do next.
- Changed: the editor’s map previews tell Mapsemble they are previews, so they count no views and the site is not listed as showing the map until a page does.
- Fixed: a map’s edit screen offers “Create a new map on Mapsemble” when the account has no maps yet.
- Fixed: an account’s empty map list is no longer remembered for five minutes, so a first map shows up at once.
- Developer: every request to Mapsemble carries
X-Mapsemble-Client: wordpress/<version>. New REST routes undermapsemble/v1/onboarding/for users withedit_mapsemble_map_data. Building a map, reading a spreadsheet and sending typed rows may take up to 50 seconds; other calls keep 15. The widget settingsourcemarks the editor’s preview frame.
0.5.1
- Changed: the plugin is now called “Mapsemble – Store Locator & Listing Maps”, and its description says what it builds and that it is free up to 150 locations per map. No functional changes.
0.5.0
- Changed: the Mapsemble location editor opens in a new tab, with the map beside it, instead of in a frame inside the admin. The sign-in token is minted when you click, not when the screen loads.
- Added: the block’s map picker is searchable — type part of a name or paste an id. Maps are listed newest first with “Another map id…” at the top, and maps that share a name are told apart by their creation date and a short id. The map edit screen’s select follows the same order and gains a filter box on long lists.
- Added: a chosen map renders live in the block editor, and a “Change map” toolbar button picks another.
- Added: “Find an address” in a post’s Map location box looks the address up through Mapsemble and fills in the coordinates, with a link to check the spot on OpenStreetMap.
- Added: with one of your maps chosen, the block’s Filters panel lists that map’s filter slugs; clicking one adds it to the initial filters.
- Added: a map built from this site shows how many posts it currently serves, and saving warns about always-on filter terms that do not exist.
- Added: Mapsemble → Maps is searchable and paginated, newest first, with a Created column and All / Hosted on Mapsemble / Built from this site views. The location editor’s heading names the map and links back to the list.
- Added: the Built from this site list shows each map’s shortcodes with a Copy button, and a shortened map id.
- Changed: the Mapsemble menu reads Maps / Built from this site / Settings. Maps (formerly Map data) lists your account’s maps and comes first; the site-fed maps (formerly Maps) are under Built from this site. Links are unchanged.
- Changed: new Map blocks insert as Wide, so desktop visitors get the desktop layout; “None” is still a choice. Blocks already set to Wide or Full now render that way on the published page; others are unchanged.
- Changed: with “Fill the visible viewport” off,
heightis the map’s exact height, on existing blocks too; with it on, the sidebar calls it “Minimum height”. - Changed: switching a block’s “Which map” to “Select a map” clears the sample’s still from the canvas, which now just asks which map.
- Changed: map screens say “Map saved.” instead of “Post published.”, bulk actions count maps, and creating a map on Mapsemble from the edit screen confirms it.
- Changed: the Pro plan note appears once, inline; “Add them on Mapsemble” links straight to the map’s filters or sort panel in the Mapsemble builder.
- Changed: on a map’s edit screen the manual map id is folded away unless the list is empty, and the meta-key and ACF inputs show only for their location source.
- Changed: on Settings, “Finish connecting” appears only once the automatic connect gives up, and the uninstall choice has its own Data section.
- Fixed: a typo in the location box no longer erases the saved location — invalid input leaves it untouched and says what is wrong. Comma decimals work, and a pasted “lat, lng” pair fills both fields.
- Fixed: an unknown or unavailable map no longer leaves a screen-tall blank box — visitors see the section collapse, and editors get a notice naming the likely cause, on the page and in the block preview.
- Fixed: a one-click connect or reconnect ends on the “Connected to Mapsemble” notice instead of a silent reload.
- Fixed: with
MAPSEMBLE_CLIENT_IDdefined inwp-config.php, saving the settings no longer wipes the stored client ID; a save that only changes the uninstall choice keeps the cached token and map list. - Fixed: the “cannot reach this site” warning no longer shows when Mapsemble itself runs on your local network; private-network and loopback addresses now count as local.
- Fixed: an always-on filter whose only slug is
0no longer drops out and lets the map serve every post. - Fixed: accessibility — the location-source radios are a fieldset with a legend, location box errors, filter matches and copied shortcodes are announced, address search keeps focus, and the Maps list’s actions column is labelled.
- Developer: new REST routes
mapsemble/v1/geocodeandmapsemble/v1/map-filters, for users who can edit posts; theloadErrorTextwidget setting is gone.
Older releases are listed in changelog.txt, shipped with the plugin.
