Map Blocks: Show a Location Without Hiding the Address

A map block helps a visitor understand where a real place is and move from reading to navigation. Its durable content is the verified address in HTML; the visual map is an optional orientation aid. The default implementation reserves the map area, shows a lightweight static fallback, and loads an approved interactive provider only after the visitor asks for it.

National Gallery
Trafalgar Square, London WC2N 5DN, United Kingdom
Map not loaded. Open the location in your map app, or activate Load interactive map when you need to inspect the surrounding streets.

This rendered facade is useful before any third-party request. It names the place, exposes the address as selectable text, explains the unloaded state, and provides two clear routes: open an external map or deliberately load the embedded one.

Why this element matters

Location questions are practical. A visitor may be deciding whether a branch is close enough, checking which side of a railway line it sits on, finding the correct entrance, or comparing public transport with parking. A map reduces the mental work of translating an unfamiliar address into spatial context. It can make nearby landmarks and street relationships visible faster than a paragraph.

That convenience does not make the map the source of truth. Visitors may copy an address, send it to another person, or read it with assistive technology. Map tiles cannot reliably support those actions, and weak data, privacy settings, or provider failure may block them. The address must remain useful without the map.

An embedded map can add an iframe, JavaScript, fonts, images, and third-party requests. Those resources compete with the page’s answer and may disclose an IP address or initiate storage subject to consent. A visitor who never uses the map should not pay that cost.

Machine extractability means software can identify the place without interpreting map pixels or executing the provider. Search crawlers, AI systems, screen readers, translation tools, and local data pipelines need a place name, complete postal address, coordinates where governed, and a stable destination link in HTML or structured fields. An iframe URL is not a dependable address. Provider labels can change, and pins can be slightly misplaced. The same verified location record should feed the visible address, the map marker, navigation link, and any eligible structured data.

The element writing rules take precedence: choose a typed element by purpose, not appearance. If the purpose is spatial orientation around one verified place, use a map block. If the purpose is to publish contact details, use an hours and contact block or NAP block and let the map consume the same address record. If the purpose is to reserve a time, use a booking block .

When to use it

Use a map block when seeing the place in its surroundings helps the reader complete a location-dependent task. Typical uses include a shop, office, clinic, venue, pickup point, showroom, hotel, attraction, branch, event entrance, or service-area boundary. It is especially useful when the entrance differs from the postal address, nearby roads are confusing, accessibility routes need explanation, or public transport and parking affect the visit.

Confirm the marker against the actual entrance or service point rather than accepting the provider’s first geocoding result. For a place inside a larger building, state the floor, unit, or entrance in text.

Near-miss cases often create attractive but unhelpful maps:

• A list of cities served: this is a service-area statement, not proof of a physical location. Do not drop pins at city centers and imply offices.
• A mailing address with no visitor access: publish the postal details and say visits are unavailable. A map would imply an unsupported arrival action.
• A remote or online-only company: a registered office may be legally relevant, but it does not become a customer destination because an embed can locate it.
• Turn-by-turn instructions: link to a navigation provider and provide route-specific notes. A static embedded map cannot account for traffic, closures, or the visitor’s starting point.
• Many locations: use a location finder with a textual result list. A cloud of pins cannot replace individual branch pages.
• Proof of local presence: a map is not evidence that a team operates there. Support the claim with consistent identity, address, contact, opening, and branch-specific content.
• Decorative geographic context: if the location does not affect the task, omit the map. A city skyline or regional outline belongs to a different visual purpose.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Place the map immediately after the place name, complete address, and any visit-critical qualifier. On a location page, the usual sequence is introduction, address and contact facts, map, arrival notes, hours, then the visit or booking action. If directions are the primary answer, summarize them before the map.

Keep the address, map facade, load control, fallback link, caption, and direction note in one labelled region. The visitor should not need to cross a testimonial or marketing section to find the address that belongs to the pin. A “Get directions” link must use the same coordinates or place identifier as the displayed marker.

The block may sit near opening hours for the same branch, but not beside a conflicting address, another map, autoplaying video, or advertisement styled like a control. Do not place it inside a carousel, accordion, required modal, hidden tab, or narrow table cell.

Do not put the map between a warning and the instruction it qualifies, or between a booking action and its prerequisites. Never overlay essential address text, consent wording, or the only directions link on map tiles. On mobile, preserve this reading order: place name, address, visit qualifier, fallback, load control, map region, then directions.

Anatomy

1. Place name: identifies the branch, venue, or destination represented by the marker.
2. Complete text address: includes every address line, locality, postal code, and country needed to distinguish the place.
3. Visit qualifier: states entrance, unit, floor, appointment requirement, visitor restriction, or accessibility fact when it changes arrival.
4. Reserved viewport: fixes width and aspect ratio before interactive resources load, preventing layout movement.
5. Static fallback: provides useful spatial context without scripts; it must be a real generated asset before it is referenced.
6. Marker: represents the verified arrival point, not merely a postcode or administrative centroid.
7. Load control: is a real button with a specific accessible name, such as “Load interactive map for National Gallery.”
8. Provider notice: names the third party and explains that activation may connect to it.
9. Directions link: opens a stable HTTPS destination for navigation without requiring the embedded player.
10. Caption or landmark note: explains the map’s useful conclusion, such as the entrance facing a named street.
11. Location record: supplies governed coordinates, place identifier, and verification date to the renderer.
12. Failure state: preserves the address, directions link, and retry choice if the provider cannot load.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

Every variant keeps the address in HTML, reserves the map dimensions, and provides a direct directions link. Only the loading behavior changes.

Static map with external directions — lowest cost

Use an optimized map image when orientation helps but panning and zooming do not. Alternative text states its spatial conclusion; the caption carries landmarks. Publish the path only after the asset exists.

Click-to-load interactive map — default

Display a static fallback or neutral reserved panel first. A button loads the approved iframe after explicit activation. This protects page speed and makes the third-party connection intentional while keeping pan, zoom, and street inspection available on demand.

Consent-gated map

Use this when the site’s privacy policy requires consent before contacting the provider. Explain the consequence in plain language and offer the directions link without requiring consent. Declining must not hide the address or prevent the rest of the page from working.

Always-loaded interactive map — measured exception

Use only when interaction is central, provider contact is permitted, and field measurement accepts the cost. Lazy loading can still initialize as the visitor approaches. Keep a server-rendered fallback because loading="lazy" cannot prevent provider failure.

Single-location block inside a locator

For a multi-location page, pair the selected map with a textual results list. Loading one selected branch keeps the interaction understandable; changing selection updates the place name, address, marker, and directions link together. The list remains usable without the map.

Parameters

“Source” means where the renderer obtains the authored value. The authoritative location system remains responsible for verifying the actual address and coordinates.

The renderer must build provider URLs from allowlisted identifiers and numeric coordinates. Authors must not paste arbitrary iframe HTML, API keys, access tokens, or JavaScript into the body. Six decimal places locate a point to much finer precision than a visitor normally needs; retain fewer digits when publishing an exact private entrance would create a safety or privacy risk.

Syntax and code examples

These portable examples describe one canonical content model. A project must implement and test the corresponding renderer before authors use the syntax in production.

Portable Markdown directive

:::map{variant=facade place-id="north-street-clinic" latitude=51.454514 longitude=-2.587910 zoom=16 aspect-ratio="4/3" provider=osm directions-url="https://www.openstreetmap.org/directions?to=51.454514,-2.587910" verified=2026-08-27}
## North Street Clinic

18 North Street, Bristol BS1 3PR, United Kingdom

Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
:::

The first heading supplies title; the next line supplies the structured address; and the remaining body supplies the caption or arrival note.

Hugo shortcode mapping

Use named parameters only. This notation documents the intended adapter; it does not claim that a map shortcode already exists in this repository.

{{< map variant="facade" placeId="north-street-clinic" latitude="51.454514" longitude="-2.587910" zoom="16" aspectRatio="4/3" provider="osm" directionsUrl="https://www.openstreetmap.org/directions?to=51.454514,-2.587910" verified="2026-08-27" >}}
## North Street Clinic

18 North Street, Bristol BS1 3PR, United Kingdom

Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
{{< /map >}}

The adapter must reserve the ratio, render the address and fallback on the server, and create the iframe only after the declared trigger. It must never expose a provider API key in authored content.

WordPress block

<!-- wp:amicited/map {"variant":"facade","placeId":"north-street-clinic","latitude":51.454514,"longitude":-2.587910,"zoom":16,"aspectRatio":"4/3","provider":"osm","directionsUrl":"https://www.openstreetmap.org/directions?to=51.454514,-2.587910","verified":"2026-08-27"} -->
<h2>North Street Clinic</h2>
<address>18 North Street, Bristol BS1 3PR, United Kingdom</address>
<p>Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.</p>
<!-- /wp:amicited/map -->

A native block should store coordinates as numbers, keep address fields structured, validate the provider, and render a safe server-side facade. Editor preview may show a static representation rather than initializing the full provider.

Good and bad examples

Good

North Street Clinic
18 North Street, Bristol BS1 3PR, United Kingdom
Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
Load interactive map · Open directions in a map app

This works because the visitor can identify, copy, and navigate to the place without the embed. The entrance note resolves a real arrival ambiguity. Loading the third party is a choice, and both actions clearly state what happens.

Bad

Find us here!
[full-width interactive map with an unlabeled pin]

This fails because “here” does not identify a place, the address exists only inside provider pixels, and the pin may represent a postcode rather than an entrance. The eager map adds cost even for visitors who do not use it. There is no fallback, verification date, arrival note, or accessible navigation link. Adding an address to the iframe’s title would improve the frame label but would not create selectable page text.

Schema markup and accessibility

A map block has no dedicated Schema.org type. Verified fields may feed the appropriate Organization, LocalBusiness subtype, Place, PostalAddress, or GeoCoordinates when the page represents that entity. Use one shared location record; the visible address, marker, canonical branch URL, and JSON-LD must agree.

Do not add hasMap solely to make the page look more complete. When used, it should point to a stable map URL for the same place, not an expiring session URL or an iframe endpoint with an exposed key. A service-area business without a public customer location should describe its service area honestly and must not publish invented premises or overly precise private coordinates.

Accessibility begins with independence from the map. Put the place name and full address in HTML, using <address> only for relevant contact information. Provide a normal directions link. Describe entrances, landmarks, transit, parking, and step-free access in text. Static-map alternative text should communicate the useful conclusion, not list every street.

The load control must be a keyboard-operable <button> with visible focus and an accessible name tied to the place. Loading must not move focus unexpectedly. After activation, announce a short status such as “Interactive map loaded,” then keep focus on the initiating control or move it only when the interface has a documented keyboard entry point. Give each iframe a unique title, for example “Interactive street map for North Street Clinic.”

Provider controls must remain operable at narrow widths and 200% zoom. Do not trap keyboard focus inside the iframe. Do not rely on pin color, drag gestures, hover, or visual street labels for essential information. If the map fails or consent is declined, keep the reserved region stable and expose the address, arrival note, external directions link, and retry action.

Writing rules

Lead with the official public place name in two to ten words. Follow with the complete postal address as stored in the governed location record. Do not abbreviate away a unit, building, locality, or postal code needed to reach the correct entrance. Include the country when the page can receive international traffic or when the city name is ambiguous.

Add one arrival note of 8–35 words only when it changes what the visitor should do. Name a durable landmark or entrance relationship: “Use the courtyard entrance beside the pharmacy” is useful; “You can’t miss us” is not. Time-sensitive road closures, construction routes, and temporary entrances need an owner and review date elsewhere in the content system.

Use one map block for one selected destination. A locator may switch that destination, but every selected state must update the title, address, marker, caption, and link atomically. Show one primary marker by default. Secondary landmarks may appear only when they explain arrival and are visually distinguishable in text and controls.

Keep control labels literal: “Load interactive map,” “Open directions,” and “View accessible entrance.” Avoid vague labels such as “Explore,” “See more,” or “Click here.” State the provider before activation when a connection has privacy implications.

Never place phone numbers, opening hours, promotional claims, reviews, prices, booking forms, or long parking policies inside the interactive canvas. Those facts belong in HTML and in their own typed elements. Never publish an API key, a user’s live position, a private residential entrance, fabricated office pins, unverified service areas, or coordinates copied from an unchecked geocoder. The map must not imply visitor access where none exists.

Verify the address and marker at publication, after a location change, and during scheduled review. Provider roads and labels can change independently; the organization still owns the accuracy of its location record and arrival instructions.

Post types that use it

The postTypes frontmatter field is the source for this implementation matrix.

QA checklist

• The place name and complete address appear as selectable server-rendered text outside the map.
• The marker points to the verified public arrival point rather than a postcode or building centroid.
• The address, coordinates, place identifier, directions link, and structured data come from the same governed record.
• The block explains any unit, floor, entrance, appointment rule, or accessibility route needed to arrive.
• The default implementation avoids third-party requests until explicit activation or valid consent.
• An always-loaded exception has a documented purpose, privacy basis, and measured performance budget.
• Width and aspect ratio are reserved before image, iframe, or provider code loads.
• Any static image path points to a real approved asset and has useful alternative text.
• The load control is a button with a place-specific accessible name and visible focus.
• The iframe, when created, has a unique descriptive title and does not trap keyboard focus.
• The address, directions link, arrival note, and retry path remain usable when scripts, consent, or the provider fail.
• Essential information does not depend on pin color, hover, dragging, zoom, or map labels.
• The layout works at narrow widths and 200% zoom without covering provider controls.
• The page does not claim a public office, entrance, or service area that the organization cannot verify.
• No API keys, access tokens, user locations, private coordinates, or arbitrary iframe URLs appear in authored content.
• Multi-location implementations retain a keyboard-accessible text list and synchronize the selected branch atomically.
• Schema, if present, describes the same real entity and address shown to visitors.
• The verification date and review owner meet the site’s local-data maintenance policy.

A map block succeeds when losing the map changes convenience, not meaning. The reader still knows the place, how to reach it, and what to expect; the provider remains optional.