Map setup

The Map section (sections/map.liquid) renders a single-location OpenStreetMap iframe, an <address> block, and an opening-hours list — all from theme editor settings. It ships in Uisce with zero external JavaScript runtime and no API keys, so it meets the Shopify Theme Store review criteria with no extra work on your part.

If you want a multi-location directory with per-location phone / map-link cards, use the existing Store locator section instead. Map is the simpler single-pin primitive.

Quick start

1. In the theme editor, add the Map section to any page, or to a custom section group.
2. Fill in the address fields: Address line 1, City, Country.
3. Enter your latitude and longitude in the Latitude and Longitude fields. See How to look up lat/lng below.
4. (Optional) Add up to 7 Hours blocks — one per weekday.
5. Save.

That's it. The iframe tile pulls from OpenStreetMap and the address / hours block renders server-side — no extra setup, no build step, no API keys.

Why latitude / longitude — not just the address?

OpenStreetMap's embed iframe takes a bounding box (bbox=) and a marker coordinate. The theme computes the bbox for you from your zoom_padding_m setting (default 550 metres — a neighbourhood-scale view centred on the pin). We intentionally do not call a geocoding API at render time — the public Nominatim service has a strict 1-request-per-second policy and asks that themes never geocode in response to visitor traffic.

So you do the geocoding once, at setup time, and paste the numbers into the section settings.

Looking up latitude and longitude

You have three easy options. Pick whichever suits your workflow.

Option A — the OpenStreetMap website (recommended, zero dependencies)

1. Go to https://www.openstreetmap.org.
2. Search for your address in the search bar at the top-left.
3. Click the matching result — the URL updates to include #map=18/LAT/LNG (for example #map=18/53.3498/-6.2603).
4. Copy LAT and LNG from that URL into the section settings.

Alternatively: right-click the pin on the map and choose "Show address". The lat / lng appear in the details panel on the left.

Option B — Google Maps

1. Open https://maps.google.com and search for your address.
2. Right-click the pin — a context menu appears with the lat / lng at the top (e.g. 53.3498, -6.2603).
3. Click the coordinate to copy it, then split it into the two fields in the section settings.

Option C — the bundled geocode-address.mjs script (for developers shipping multiple addresses)

If you are setting up several addresses in bulk — for example populating the five preset demo stores — there is a Node script at scripts/geocode-address.mjs that queries the public Nominatim service with the proper User-Agent and the mandatory 1.1-second pause between requests.

Run it from the theme root:

node scripts/geocode-address.mjs "123 Main St, Dublin, Ireland" "42 Second Ave, Cork, Ireland"

The script prints a JSON array to stdout with { address, lat, lng, display_name } per query. Copy the numbers into the section settings.

Use responsibly

The public Nominatim service is free but the usage policy requires a valid User-Agent (the script supplies one) and limits heavy use (over ~1000 requests per day) to private instances. If you run into rate-limit errors, wait a minute and try again.

Section settings reference

Setting	Type	Default	Notes
Pin label	Text	—	Displayed above the address — typically your business name. Used with the Schema.org LocalBusiness microdata.
Iframe title	Text	—	Screen-reader label for the iframe. Leave empty to fall back to the translated sections.map.iframe_title key.
Address line 1	Text	—	Street number and street name.
Address line 2	Text	—	Suite, floor, unit, etc. Optional.
City	Text	—	—
Country	Text	—	Full country name (e.g. "Ireland", not "IE").
Latitude	Text	—	Decimal degrees (e.g. 53.3498). Positive = north.
Longitude	Text	—	Decimal degrees (e.g. -6.2603). Positive = east.
Zoom padding (metres)	Range	550	Half the side-length of the bounding box around the pin. 550 m is the neighbourhood default. Drop to 50 m for a tight single-block view, raise to 5000 m for a city view, or up to 50000 m for a regional view.

Hours blocks

Each Map section accepts up to 7 Hours blocks (one per weekday). Each block has:

• Day — free text (e.g. "Monday", "Lun.", "月曜日"). We do not force a day order — the order in which you drag the blocks in the theme editor is the order they render.
• Hours — free text (e.g. "09:00 – 17:00"). Leave empty to render the translated "Closed" key.

The resulting <dl> uses Schema.org's openingHours microdata on every <dd>, which helps Google show your opening hours in rich results.

Privacy and security

• No API keys — the iframe loads directly from openstreetmap.org/export/embed.html with no auth.
• referrerpolicy='no-referrer' — OpenStreetMap's tile server receives only the visitor's IP address, not the full URL they came from.
• allow='' (empty) — the iframe cannot request geolocation, camera, clipboard, or other browser APIs.
• No sandbox attribute — adding sandbox without explicit token flags blocks all iframe content from loading (including the OSM tiles). Browser origin isolation already protects you.
• No JavaScript in the section — zero added bytes to your critical-path JS budget.
• OpenStreetMap foundation is a non-profit and does not profile visitors or serve ads on the tile layer.

Merchants on plans that set a restrictive Content-Security-Policy (via Shopify Plus or an enterprise security app) may need to allow https://www.openstreetmap.org in the CSP frame-src directive.

Troubleshooting

The iframe shows a blank frame. Check that your latitude and longitude are both filled in (an empty field falls back to 0 which plots the marker in the Gulf of Guinea). Verify the lat / lng by pasting them into https://www.openstreetmap.org — you should see the map centre on your location.

The pin is in the wrong spot. Swap the lat / lng values — a very common mistake is entering longitude into the latitude field and vice versa. Latitude is -90 to 90; longitude is -180 to 180.

The map is too zoomed in / out. Adjust the Zoom padding (metres) range setting. Smaller values zoom in tighter; larger values zoom out. 550 m is a good neighbourhood default; 5000 m shows a small city; 50000 m shows a region.

The hours list rendered in the wrong order. Drag the Hours blocks in the theme editor — the render order follows the block order, which you can change freely.

I see English "Closed" text instead of my language. The fallback uses the storefront's sections.map.closed translation key, which is provided in all 50 locales. If you see English on a non-English storefront, check that the locale is published and not overridden by a language you have disabled.