Map

The Map field stores a place: an address and, optionally, its coordinates. Editors search an address, click the map or drag the marker; your site shows a map and a "View on map" link.

The JSON column always holds the complete value. The two companion columns are filled automatically on every save so that you can filter and sort posts by location (for example "within 10 km"). A group that has a Map field therefore has three columns for it.

Choose the map service

The map service is a site-wide choice in WPM Fields › Settings, card Maps.

Until a Google key is saved, the notice "Until a key is saved, maps keep using OpenStreetMap." applies and OpenStreetMap stays in use, even when Google Maps is selected.

Editors' and visitors' browsers contact the chosen service directly to load map tiles, and editors' address searches are sent to the geocoder. Mention this in your privacy policy. The OpenStreetMap services are public and have a usage policy; very busy sites should use Google Maps or their own tile service.

Type settings

Edit screen

• An address box (placeholder "Search for an address…") with a Search button. Press Enter or Search, then pick a result.
• A map. Click to place the marker, or drag the marker.
• Latitude and Longitude boxes you can type into (latitude from -90 to 90, longitude from -180 to 180).
• Clear removes the place.

The zoom the editor leaves the map at is saved with the value.

What is accepted when saving

The value is empty (null) only when there are no coordinates and no address. An address without coordinates is a valid value (lat and lng are null).

wpmcf_update_field() takes the array, or a JSON string of it. A plain "41.0,28.9" string is not parsed by wpmcf_update_field() and clears the field; only CSV imports accept lat,lng (also lat;lng) and a JSON object.

Template usage

$place = wpmcf_get_field( 'shop', 'location' );
// [
//   'address' => 'Istanbul',
//   'lat'     => 41.0082,
//   'lng'     => 28.9784,
//   'zoom'    => 12,
// ]

$lat = wpmcf_get_field( 'shop', 'location', null, [ 'path' => 'lat' ] );   // 41.0082

lat and lng are null for an address-only value. Guard before you use them:

if ( $place && null !== $place['lat'] ) {
    printf( 'https://maps.example/?q=%s,%s', esc_attr( (string) $place['lat'] ), esc_attr( (string) $place['lng'] ) );
}

The automatic output (wpmcf_the_field() and the shortcode):

[wpmcf_field group="shop" field="location" wrap="false"]

<div class="wpmcf-map-field">
  <p class="wpmcf-map-field__address">Istanbul</p>
  <div class="wpmcf-map" data-lat="41.0082" data-lng="28.9784" data-zoom="12" data-height="320"
       data-label="Istanbul" role="region" aria-label="Map of Istanbul"></div>
  <a class="wpmcf-map-field__link" href="https://www.openstreetmap.org/?mlat=41.0082&amp;mlon=28.9784#map=12/41.0082/28.9784">View on map</a>
</div>

• The <div class="wpmcf-map"> is drawn into a live map by a small script that loads only on pages that print a Map field.
• With an address but no coordinates, only the address and a View on map link (a search link) are printed; no map is drawn.
• The link points to OpenStreetMap, or to Google Maps when Google is the provider.

Search by distance: see the wpmcf_distance query argument of wpmcf_query_posts() in Developer API.

Troubleshooting

• The map is blank on the site. Check the browser console. For Google Maps the key must allow your site's domain and the Maps JavaScript API. Switch the provider to OpenStreetMap to test.
• Address search finds nothing. Try a shorter address, or place the marker by hand. With Google the Geocoding API must be enabled for the key.
• Latitude and longitude disappeared on save. One of them was empty or out of range; both are dropped together.
• The old Google marker shows. Enter a Map ID in Settings › Maps.
• Existing posts have no coordinates in the new columns. The companion columns are filled when a value is saved; resave the posts after changing a field to the Map type.