{"result":{"depiction_url":null,"edges":{"observes":{"objects":[{"created":"2026-10-06T14:21:18Z","object_id":{"id":1517,"is_a":["text","documentation","reference","notification"],"name":"doc_notification_pivot_fields","title":"observe_pivot_fields\/3","uri":"https:\/\/zotonic.com\/id\/1517"},"seq":1},{"created":"2026-10-06T14:21:18Z","object_id":{"id":1801,"is_a":["text","documentation","reference","notification"],"name":"doc_notification_rsc_get","title":"observe_rsc_get\/3","uri":"https:\/\/zotonic.com\/id\/1801"},"seq":2},{"created":"2026-10-06T14:21:18Z","object_id":{"id":1823,"is_a":["text","documentation","reference","notification"],"name":"doc_notification_postback_notify","title":"observe_postback_notify\/2","uri":"https:\/\/zotonic.com\/id\/1823"},"seq":3},{"created":"2026-10-06T14:21:18Z","object_id":{"id":1982,"is_a":["text","documentation","reference","notification"],"name":"doc_notification_search_query","title":"observe_search_query\/2","uri":"https:\/\/zotonic.com\/id\/1982"},"seq":4},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2135,"is_a":["text","documentation","reference","notification"],"name":"doc_notification_pivot_update","title":"observe_pivot_update\/3","uri":"https:\/\/zotonic.com\/id\/2135"},"seq":5},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2341,"is_a":["text","documentation","reference","notification"],"name":"doc_notification_search_query_term","title":"observe_search_query_term\/2","uri":"https:\/\/zotonic.com\/id\/2341"},"seq":6}],"predicate":{"id":2550,"is_a":["meta","predicate"],"name":"observes","title":{"_type":"trans","tr":{"en":"Observes"}},"uri":"https:\/\/zotonic.com\/id\/observes"}},"subject":{"objects":[{"created":"2026-10-06T14:21:18Z","object_id":{"id":2555,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_reference","title":"Reference","uri":"https:\/\/zotonic.com\/id\/2555"},"seq":1},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2562,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_site_administrator","title":"Site administrator","uri":"https:\/\/zotonic.com\/id\/2562"},"seq":2},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2586,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_search_and_discovery","title":"Search and discovery","uri":"https:\/\/zotonic.com\/id\/2586"},"seq":3},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2599,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_api_and_integration","title":"API and integration","uri":"https:\/\/zotonic.com\/id\/2599"},"seq":4},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2603,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_configuration","title":"Configuration","uri":"https:\/\/zotonic.com\/id\/2603"},"seq":5},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2609,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_geolocation","title":"Geolocation","uri":"https:\/\/zotonic.com\/id\/2609"},"seq":6},{"created":"2026-10-06T14:21:18Z","object_id":{"id":2635,"is_a":["categorization","keyword","keyword_architecture"],"name":"zotonic_topic_module","title":"Module","uri":"https:\/\/zotonic.com\/id\/2635"},"seq":7}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"id":2769,"is_a":["text","documentation","reference","module"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/2769"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_external_4_mod_geomap","page_url":{"en":"https:\/\/zotonic.com\/docs\/2769\/mod_geomap","x-default":"https:\/\/zotonic.com\/docs\/2769\/mod_geomap"},"preview_url":null,"resource":{"version":29,"pivot_location_lat":null,"title":"mod_geomap","is_authoritative":true,"body":"

Add resource locations, map display, geocoding, and geographic searches to\nZotonic. Enable mod_geomap<\/code> on the site; it depends on mod_l10n<\/code>.<\/p>\n

Resource locations<\/h2>\n

The admin location editor stores location_lat<\/code>, location_lng<\/code>, and\nlocation_zoom_level<\/code>. Coordinates are latitude and longitude in degrees.\nResource pivoting updates pivot_location_lat<\/code>, pivot_location_lng<\/code>, and the\nquadtile pivot_geocode<\/code>. Explicit coordinates take precedence over a location\nderived from address fields. An already supplied pivot location is retained\nwhen no explicit coordinates are present.<\/p>\n

Resource reads expose computed_location_lat<\/code> and computed_location_lng<\/code> from\nthe quadtile, or from numeric explicit coordinates when no quadtile is available.\nUse these computed properties for map display and the geomap_distance<\/code> filter.<\/p>\n

Address geocoding uses the resource's street, city, state, postcode, and country.\nFull address lookups try Google Maps and fall back to OpenStreetMap Nominatim;\ncountry lookups can use the module's precoded country coordinates. Address\nlookup can therefore send address information to an external service.<\/p>\n

Configuration<\/h2>\n

Set these per-site keys under mod_geomap<\/code>:<\/p>\n
Key<\/th>Purpose<\/th><\/tr><\/thead>
is_auto_geocode<\/code><\/td>Automatically use external geocoding for resource addresses; defaults to true<\/code>.<\/td><\/tr>
provider<\/code><\/td>googlemaps<\/code> selects Google Maps; otherwise the bundled map templates use OpenLayers.<\/td><\/tr>
google_api_key<\/code><\/td>Key used for Google geocoding and the browser Maps script.<\/td><\/tr>
location_lat<\/code><\/td>Initial latitude when the resource has no location; the admin template falls back to 0<\/code>.<\/td><\/tr>
location_lng<\/code><\/td>Initial longitude when the resource has no location; the admin template falls back to 0<\/code>.<\/td><\/tr>
zoomlevel<\/code><\/td>Initial zoom when no resource-specific zoom is available.<\/td><\/tr><\/tbody><\/table>\n

The OpenLayers admin map defaults to zoom 2<\/code> without a location and to 15<\/code>\nfor a located resource without its own zoom setting. The static-map tag has its\nown default zoom of 14<\/code>. The provider setting selects map presentation; it does\nnot change the geocoding fallback order. The Google key is exposed to map\nscripts through m.geomap.google_api_key<\/code> and is not a server-only secret.<\/p>\n

Set mod_geomap.is_auto_geocode<\/code> to false<\/code> to prevent resource pivoting from\nsending addresses to Google Maps or Nominatim. Existing coordinates are retained\nwhen a lookup is skipped. Explicit coordinates and local precoded lookups still\nwork. The admin's Set to entered address<\/strong> button and explicit Erlang geocoding\ncalls remain available and can contact external services.<\/p>\n

Nearby search<\/h2>\n

The geo_nearby<\/code> search accepts a resource id<\/code> with pivoted coordinates or an\nexplicit latitude<\/code> and longitude<\/code> pair. distance<\/code> is in kilometers and defaults\nto 10<\/code>. Use cat<\/code> to restrict resource categories.<\/p>\n

{% with m.search.geo_nearby::%{ id: id, distance: 10 } as results %}\n    {% for location_id in results %}\n        <a href="{{ location_id.page_url }}">{{ location_id.title }}<\/a>\n    {% endfor %}\n{% endwith %}\n<\/code><\/pre>\n
The search selects a latitude\/longitude bounding box and orders results by\nsquared coordinate differences from the center. It is an approximate nearby\nsearch, not an exact circular-distance filter. The center resource is not\nexcluded. Missing or unusable center coordinates do not produce a valid query.\nThe normal Zotonic search pipeline applies resource visibility restrictions.<\/p>\n
The has_geo<\/code> search term selects resources with both pivot coordinates present;\nhas_geo=false<\/code> selects resources missing either coordinate.<\/p>\n
Admin panels<\/h2>\n
Enabling the module adds a Geolocation<\/strong> panel to resource editing. It starts\ncollapsed and loads the map lazily. The category's Show geo data on edit page<\/strong>\nfeature controls its visibility; if unset, it follows Show address<\/strong>, defaulting\nto enabled. Resources with explicit latitude or longitude also show the panel.<\/p>\n
Expand the panel to edit latitude, longitude, and zoom level (0<\/code> through 29<\/code>).\nClick the map to select a location, or use these controls:<\/p>\n
  • Set to current location<\/strong> requests the browser's location, subject to the\nvisitor's permission and browser availability.<\/li>
  • Set to entered address<\/strong> geocodes the address in the edit form. This button\nis hidden when the form has no address-country field.<\/li>
  • Clear<\/strong> removes the explicit coordinates from the form.<\/li>
  • Reset<\/strong> restores the resource's saved coordinates.<\/li><\/ul>\n
    Save the resource to persist the edited values. The indexed coordinates shown\nbelow the inputs are the computed location; pivoting updates the searchable\nlocation after a save. Clearing explicit coordinates can allow address-derived\ngeocoding to determine the location again.<\/p>\n
    Country resources also receive a World Map<\/strong> panel with Color<\/strong> and Value<\/strong>\nfields. These store map_color<\/code> and map_value<\/code> for the country data returned by\nm.geomap.countries<\/code>; they do not set the resource's coordinates.<\/p>\n
    Showing a map<\/h2>\n
    Static tile map<\/h3>\n
    Render a resource's computed location without interactive-map JavaScript:<\/p>\n
    {% geomap_static id=id zoom=14 n=2 %}\n<\/code><\/pre>\n
    Or pass explicit coordinates:<\/p>\n
    {% geomap_static latitude=52.34322 longitude=4.33423 zoom=14 %}\n<\/code><\/pre>\n
    The tag renders _geomap_static.tpl<\/code>, a grid of OpenStreetMap tile images with a\nmarker. n<\/code> defaults to two rows and columns; rows<\/code> and cols<\/code> can override each\ndimension, and size<\/code> sets the displayed tile size (default 256<\/code> pixels).\nOverride this template in the site to change its markup or styling.<\/p>\n
    For a single remotely rendered map image, include:<\/p>\n
    {% include "_geomap_static_simple.tpl" id=id zoom=14 width=440 height=280 %}\n<\/code><\/pre>\n
    This template uses the resource's computed location and the external\nstaticmap.openstreetmap.de<\/code> image service. Its default image dimensions are\n220<\/code> by 220<\/code> pixels. Both static approaches require a usable location.<\/p>\n
    Interactive OpenLayers map<\/h3>\n
    The do_geomap<\/code> widget supports panning, zooming, and markers. With the map\nprovider unset or set to openlayers<\/code>, load _js_geomap.tpl<\/code> after the site's\nstandard jQuery\/Zotonic scripts and before widget initialization. Keep the\nstandard {% all include "_html_head.tpl" %}<\/code> hook in the page head to load the\nmodule's OpenLayers CSS. Include the map scripts once per page.<\/p>\n
    {% include "_js_geomap.tpl" %}\n<div class="do_geomap" style="width: 100%; height: 400px;"\n     data-geomap='{"location_lat":52.34322,"location_lng":4.33423,"zoom":14,"marker":true}'>\n<\/div>\n<\/code><\/pre>\n
    The map container needs an explicit height. location_lat<\/code> and location_lng<\/code>\nset its center, zoom<\/code> sets the initial zoom, and marker=true<\/code> adds a marker\nthere. For resource coordinates, read id.computed_location_lat<\/code> and\nid.computed_location_lng<\/code>, check that they are numeric, and serialize the\noptions as JSON with HTML-attribute escaping rather than concatenating strings.<\/p>\n
    For multiple locations, supply a locations<\/code> array of objects containing id<\/code>,\nlat<\/code>, and lng<\/code>, with optional icon<\/code> and data<\/code>. The OpenLayers widget clusters\nnearby markers; clusterDistance<\/code>, clusterBgColor<\/code>, and clusterColor<\/code> control\ncluster presentation. Marker clicks invoke the map_infobox<\/code> wired event with\nIDs and associated data, which the site can handle to display details.<\/p>\n
    The older _geomap.tpl<\/code> is experimental and uses an older OpenLayers API; use\nthe widget with the bundled current assets for new templates.<\/p>\n
    Related components<\/h3>\n
    m.geomap.countries<\/code> reads the bundled\npriv\/data\/internet_users_2005_choropleth_lowres.json<\/code> from the\nzotonic_mod_geomap<\/code> application using code:priv_dir\/1<\/code>. No copy in the site\ndirectory is needed. Decoded geometry is cached per site for one day, or until\nthe site's depcache is flushed. Resource values and visibility checks are\napplied on every request. Flush the cache after replacing the data file to\nload the new geometry immediately.<\/p>\n
    Use geomap_distance<\/code> for distances between resource locations or coordinate\nmaps. m.geomap<\/code> exposes map configuration and country-map data. Its nearby<\/code> and\nlocations<\/code> paths currently return empty maps; use geo_nearby<\/code> for resource\nsearches instead of relying on the legacy service descriptions in the README.<\/p>\n
    The module observes resource reads, pivot updates\/fields, search queries and\nterms, and map popup postbacks. Popup resource lists are filtered for visibility.<\/p>","slug":"mod_geomap","doc_module_config":[{"default":"true","description":"Automatically look up resource addresses using external geocoding services. Disable to keep automatic lookups local; manual lookups remain available.","has_default":true,"key":"is_auto_geocode","module":"mod_geomap","type":"boolean"},{"default":""openlayers"","description":"Map presentation provider: openlayers or googlemaps. Does not change the geocoding services used for address lookups.","has_default":true,"key":"provider","module":"mod_geomap","type":"string"},{"default":"undefined","description":"Google Maps API key for server-side geocoding and browser maps. Exposed to browser scripts through m.geomap.google_api_key.","has_default":true,"key":"google_api_key","module":"mod_geomap","type":"string"},{"default":"0","description":"Initial map latitude in degrees when the resource has no location. The admin map falls back to 0; does not set resource coordinates.","has_default":true,"key":"location_lat","module":"mod_geomap","type":"float"},{"default":"0","description":"Initial map longitude in degrees when the resource has no location. The admin map falls back to 0; does not set resource coordinates.","has_default":true,"key":"location_lng","module":"mod_geomap","type":"float"},{"default":"2","description":"Initial admin map zoom (0..29) when the resource has no location or zoom setting. Located resources default to 15; static maps have a separate default of 14.","has_default":true,"key":"zoomlevel","module":"mod_geomap","type":"integer"}],"is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"doc_source_hash":"4c1f7bc4b460a8538bd48bd335be8e4523b6d715088d2038e15e5e6e2d465fc7","doc_module_observers":[{"name":"pivot_fields","page_name":"doc_notification_pivot_fields"},{"name":"pivot_update","page_name":"doc_notification_pivot_update"},{"name":"postback_notify","page_name":"doc_notification_postback_notify"},{"name":"rsc_get","page_name":"doc_notification_rsc_get"},{"name":"search_query","page_name":"doc_notification_search_query"},{"name":"search_query_term","page_name":"doc_notification_search_query_term"}],"is_featured":false,"content_group_id":{"id":2551,"is_a":["meta","content_group"],"name":"content_group_imported_docs","title":"Imported documentation","uri":"https:\/\/zotonic.com\/id\/content_group_imported_docs"},"external_module_id":{"id":4,"is_a":[],"name":null,"title":null,"uri":"https:\/\/zotonic.com\/id\/4"},"git_url":"https:\/\/github.com\/zotonic\/zotonic_mod_geomap","category_id":{"id":320,"is_a":["meta","category"],"name":"module","title":"Modules","uri":"https:\/\/test.zotonic.com\/id\/320"},"doc_source_path":".\/src\/mod_geomap.erl","publication_start":"2026-10-06T14:21:18Z","github_url":"https:\/\/github.com\/zotonic\/zotonic_mod_geomap","pivot_location_lng":null,"doc_source_kind":"external","name":"doc_external_4_mod_geomap","is_unfindable":false,"is_published":true,"pivot_geocode":null,"external_module_title":"GeoMap","created":"2026-10-06T14:21:18Z","uri":null,"doc_status":"current","is_dependent":false,"is_external_module":true,"publication_end":"9999-06-01T00:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_source_commit":"e6d27c20d16c273462eb8b6b0dfac4556a9ba391","creator_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"modified":"2026-10-06T14:35:28Z","title_slug":"mod_geomap"},"uri":"https:\/\/zotonic.com\/id\/2769","uri_template":"https:\/\/zotonic.com\/id\/:id","websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/2769"}},"status":"ok"}