Contributors: dshanske
Tags: geolocation, timezones, maps, location, weather
Requires at least: 6.2
Tested up to: 7.1
Stable tag: 6.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Adds geographic location and weather support to WordPress.
Supports adding geo coordinates, a location taxonomy, and a textual location description to a post, comment, user, or attachment. Supports adding weather data to a post or to a widget based on location. Offers choice of map displays. It supports retrieving location using the HTML5 geolocation API by default. Clicking the location icon or 'Lookup Location' will retrieve the location.
As it stores the GeoData in the classic WordPress format, Geodata can also be added from other plugins.
Automatically saves location data from image metadata when uploaded as well.
Offers the opportunity to change the displayed timezone on a per-post basis for those posts from far off locations and set this based on the coordinates of the location. While Gutenberg compatible, this is not built for Gutenberg.
Simple Location stores location and weather data inside posts, attachments, comments, and term meta...optionally other post types. This data respects a public, private or protected setting. Attachment data is automatically extracted from images if location is present, which could be extracted by any third-party downloading the picture unless removed. For all other data, it is provided by the user, who decides its ultimate use. Location data is made available through a geolocation provider...the default is currently HTML5 browser geolocation, for which the user must give consent to share). Other information is secured through use of third-party APIs to identify a location, calculate elevation, display maps, and weather conditions.
Locations uses WordPress taxonomies to allow you to generate an archive page of all posts from that location and giving it a permalink on your site. Locations are meant to reflect a more general location...for example, "Here are posts I made in California."
Locations are divided by administrative areas. The hierarchy for locations is:
- Country
- Region - state, county, or province level.
- Locality - city, town, or village level
You can choose to display the location over the textual address field. There is an option in settings to change this behavior.
The reverse geocoding system attempts to consistently retrieve the country code, region code, and locality for the location and add them to the location taxonomy. This can be potentially problematic, as if the returns from the locations added aren't consistent, it will duplicate and explode the list of terms. This is the same issue that has held back venues.
Locations are matched using the country code, region code, and locality field, and therefore, you can edit the displayed name or the region code without issue. Due to matching issues, you may have to make some manual changes and there may be some occasional duplication.
There is no top level Location page, /location included in the plugin. You can create a page at this location and use a custom template to allow it to show a list of your locations.
Venues are meant to reflect a specific location, such as a business or point of interest. Venues were originally set up as a taxonomy, and were in the plugin unimplemented for several versions. However, due to various changes since that was set up, they were switched to a custom post type. Under this setup, each venue is represented by a URL on the site that posts can be linked to. The URL contains information about the venue. At this time, venues are shared between users and it is not assumed that each user has unique venues, though this may be a consideration in future.
Venues can be set to hide the actual location for privacy purposes, for example 'Home'.
Weather consists of at minimum the current conditions and temperature but includes future parameters for use such as pressure, wind speed, wind direction degree, etc. Weather widgets are available that can be set to a specific location, a user, station ID, or airport code. Station ID is available from supported providers for weather stations, for example from a Personal Weather Station(PWS).
Stations allow for using a custom data source for weather data. This source should be a URL that returns a JSON object. When using the Custom Station provider for weather, it will look for when one of the stations defined is within 10km of your current location. It will then use the return as the current weather conditions. Please note that the return must be in the format documented in the code.
WordPress Geodata is an existing standardized way to store geodata about a post, user, comment, or term.
It consists of four fields: latitude, longitude, public, and address. This matches up with the HTML5 Geolocation fields. The W3C Geolocation Specification also provides for properties of altitude, accuracy, altitudeAccuracy, speed, and heading, which may be stored. Map Zoom is also stored as a geodata property.
Timezone is also stored as a property and is derived from the location by default or set manually.
In order to access private location information, the following custom capabilities are added to WordPress:
- 'read_{$object_type}_location' - Whether or not a user is allowed to read information locations for object types: posts, comments, terms, users. A user is always allowed to read the location from their objects.
- 'edit_{$object_type}_location' - Whether or not a user is allowed to edit information locations for object types: posts, comments, terms, users. A user is always allowed to read the location from their objects.
The plugin is designed to be extensible and anyone could write a plugin that would add additional providers.
- Map Providers are services that offer an API to retrieve maps, which are displayed on posts with a location. Providers include MapBox, Google, Mapquest, HERE, LocationIQ, Geoapify, and TomTom.
- Geocoding Providers take geo coordinates and look up the actual location/address for textual display. Geocoding Providers include Nominatim, HERE, MapQuest, Google, LocationIQ, OpenRoute and Geonames. They also support looking up coordinate for physical addresses
- Venue providers, similar to Geocoding providers, search for locations from coordinates, however, instead of returning street addresses, or municipality, it returns a list of places or venues.
- Elevation Providers optionally derive the elevation from an API when not available. Elevation is used to estimate altitude and adjust estimated sunrise/sunset levels accordingly.
- Location Providers attempt to determine your location to add it to a post. Providers include HTML5 Browser Geolocation, a Provider that takes the location setting out of the author profile, a provider that returns the exact location of a three letter airport code, and Compass, a self-hosted option for storing your location.
- Weather Providers retrieve weather data about your location and include OpenWeatherMap, Pirate Weather, Dark Sky, Weatherstack, WeatherBit, HERE and the US National Weather Service. HERE, Pirate Weather, Dark Sky, WeatherBit, and Weatherstack do not support stations. There is also an option for custom station URLs that must return the properties as they are stored in WordPress. ** The National Weather Service(US) uses their station lookup API to find the closest weather station, and uses weather from there. Therefore, if this returns no options, if you are outside the US, it will return no weather. ** The Met Office(UK) uses the distance from your current location to the nearest UK weather station and finds the closest one. However, if the nearest station is more than 100km away, it will return nothing. ** For Weather services like the NWS, Met Office, and the Custom Provider, where coverage is not worldwide, if nothing is found, a fallback provider can be set and used.
API Keys are required to use certain services.
- Mapbox - To retrieve style list inside the UI, you need a token with the styles:list scope
- OpenWeatherMap
- MapQuest
- HERE
- Compass
- Weatherstack
- Weatherbit
- GeoNames - requires a username
- LocationIQ
- Met Office UK
- OpenRoute Service
- GeoApify
- Visual Crossing
- Meteostat
- Pirate Weather
- TomTom
- AerisWeather - Individuals who share their personal weather station data with PWSWeather.com are offered a free contributor account.
At this time, all map services require an API key, but most permit limited non-commercial use. Nominatim does not require an API key, but it does ask for an email address, which will be the admin email of the site If not provided there will be no map displayed regardless of setting, reverse geo lookup will not work Without a weather provider this service will not work.
API Keys may have free limits, or may incur fees if overused. This plugin only uses a request when you post, which is usually well within the free tier which is usually thousands of requests. In all cases, you must comply with the provider's terms of use.
The appropriate API keys should be entered in Settings->Simple Location or will move to Indieweb->Location if the Indieweb plugin if installed.
add_post_type_support( 'geo-location');
add_post_type_support( 'weather' );
The software uses two custom features to declare that the post type supports these features, otherwise the location and weather features do not show in the editor.
The terms of service of most map providers expressly forbid this. While the likelihood of one of these providers coming after an individual is slim, this would be a violation of WordPress plugin guidelines. This is why the plugin does not save maps to the media library.
Geoapify's terms allow storing its static maps, so Geoapify maps are served from your site. The first time a map is shown, your site fetches it from Geoapify, stores it in wp-content/uploads/sloc-maps, and serves it from there. Your API key stays on your server, and visitors' browsers never contact Geoapify.
The image links are signed with a secret only your site knows, so nobody else can use your site to request other maps with your key.
These settings appear under Map Settings when your map provider allows storing its maps:
- Serve Maps From This Site: on by default. Turn it off to load maps from the provider, with the API key in the image link.
- Refresh Stored Maps After (Days): 30 by default. After this many days, the next page that shows a map fetches it again and replaces the stored image in place. Pages cached with the old image keep working. If the provider can't be reached, the stored image is still shown. 0 never fetches stored maps again. A provider whose terms limit how long maps may be stored is refreshed at least that often.
- Clear Stored Maps: deletes every stored map image. Stored maps are otherwise never deleted, including maps of locations you later changed or made private. Pages kept by a page cache may show broken images until their cache expires.
Developers can change the refresh age with the sloc_map_cache_max_age filter, and the storage directory with the sloc_map_cache_directory filter.
The other self-serve option is to self-host a caching static map API endpoint (see the custom map provider below).
For most map providers, the map image is loaded directly from the provider, so the API key is part of the image link and anyone viewing the page can read it. The same key is often used for geocoding, elevation, venues or weather, which your server requests itself.
To limit what someone can do with a visible key, Google, HERE, LocationIQ and MapQuest have an optional Map API Key setting. Use a separate key there that only allows static maps and is restricted to your site. If it is empty, the provider's main key is used for maps too.
Don't restrict your main key to your site's domain. Requests your server makes don't come from a web page, so a domain restriction would block geocoding and the other lookups.
Google: Use a separate key restricted to the Maps Static API. Then set up URL signing:
- Copy the URL signing secret from the Secret Generator on the Credentials page of the Google Cloud console, in the same project as the map key, into the Google Maps URL Signing Secret setting.
- On the Quotas page for the Maps Static API, set "Unsigned requests per day" to 0, so Google refuses map links that weren't signed by your site.
- A signed link can't be changed to request a different map. Unlike a website restriction, signing still works where no referring page is sent, such as in feed readers and email.
HERE: HERE restricts keys by app, not by key, so create a second app for maps:
- In the HERE platform, open Access Manager, create a new app, and create an API key for it. Enter that key as the HERE Map API Key.
- Open the new app's Trusted domains tab, turn on "Enable Trusted domains", and enter your site's domain without a path, for example
example.com. Changes can take up to 30 minutes to take effect. - Leave trusted domains off for the app that holds your main HERE key, which your server uses for geocoding and weather.
- Maps may not load where no referring page is sent, such as some feed readers and email.
Geoapify: Geoapify maps are served from your site, so the key is never shown to visitors and doesn't need a separate map key. Every Geoapify request comes from your server, so you can restrict the key to your server's IP address:
- In Geoapify's MyProjects, open your project's API Keys section and add your server's outgoing IP address to the key's allowed IP addresses.
- Your host can tell you the outgoing IP address. If your server connects over both IPv4 and IPv6, add both. If the address changes, for example on some shared hosting, update the setting, or leave the key unrestricted.
The custom map provider is an endpoint you provide yourself. You can install and use the repository here, which is a fork of a project by Aaron Parecki. The custom provider was designed around the parameters in this code. All the commercial static map APIs used assemble the pieces of a map from public tile servers, which is what this code does. While the code allows for multiple tile sources, please ensure compliance with their licenses. At the least, most of them require attribution.
The server fetches every tile a map covers, so its work grows with the image size. The plugin asks it for maps no larger than 1280 by 1280 pixels, shrinking larger maps to fit.
To change this, define SLOC_STATICMAP_MAX_WIDTH and SLOC_STATICMAP_MAX_HEIGHT in wp-config.php, or use the sloc_staticmap_max_size filter.
This allows you to use a custom endpoint that returns current weather conditions in json, using the property names used by this plugin, which can be found outlined in the class-weather-provider.php file. The configuration for this takes a URL and an ID. So you could run a script that generates a static page anywhere from any source with this data.
Currently, only Visual Crossing supports historic weather data on their basic plan. Meteostat consists solely of historical data and has no current data.
Several providers, including the custom provider, the National Weather Service(US), and the Met Office(UK) only provide limited locations for retrieving weather data. This specifies where to look if the first provider fails. This may be replaced with better logic in future.
Simple Location uses WordPress Geodata to store location, as does the WordPress app. So setting location with the app should allow it to be displayed by Simple Location. The only major difference is that whether or not a location is public is set with either 0 for private or 1 for public. The spec implemented states a non-zero number is considered public. This plugin adds the option of 2, also known as protected, which shows a textual description of the location but does not display a map or geographic coordinates.
However, now that the WordPress apps no longer support location, this may be moot.
Chrome Users: Retrieves the location using the HTML5 geolocation API(available in your browser) will not work on Chrome if your website is not secure(https). This is a Chrome decision to ensure safe control of personal data.
You can take advantage of the other built-in location providers, for example, one uses the location of the user or create your own location provider as a separate plugin.
You can do so under your user profile or alternatively update using a REST API endpoint. By posting to /wp-json/sloc_geo/1.0/user with the latitude, longitude, altitude parameters, or with a geojson body, will
update the user associated with the credentials you provide to the REST API.
There are REST API endpoints to retrieve the data so it can be used in the admin under the namespace /wp-json/sloc_geo/1.0:
- /timezone which will return timezone data for a latitude/longitude or airport code
- /weather which will return the weather for a latitude/longitude or station ID
- /geocode which will return the address information for a latitude/longitude and optionally add the weather
- /lookup which will return the current location for a user based on the location provider
- /airport allows search for an airport by IATA code, ICAO code, or Municipality. Used for the airport location search
- /map which will return static map data for the provided latitude and longitude
Compass is a GPS tracking server that stores data in flat files. The instructions for installation are available in the GitHub repository. GPS data can be sent to it from iOS or Android devices using various apps.
You can filter any query or archive by adding ?geo={all|public|text} to it to show only public posts with location. Adding /geo/all to the homepage or archive pages should also work
If you add /map to any archive URL, for example, example.com/2019/map it will return a template with a map view of that archive. It uses a default template built into the theme. Being as styling this would not be customized to your theme, you can add a map-archive.php file to your theme to customize this. For taxonomies, use /map/taxonomy/term.
JetPack only began offering location display in 2017, 3 years after this plugin was created. This plugin disables their implementation as it created conflicts.
They do not offer the features this plugin does and their goal is a minimal implementation.
Why am I seeing location on private posts with the notation Hidden?
This appears to users who can read private posts when logged in. It does not appear when not logged in. The same applies to the location taxonomy. If you are not logged in, or are logged in and don't have the read_private_posts permission, you won't see posts with private locations.
The Development Version as well as support can be found on Github.
Simple Location has the concept of Providers. Providers are an abstract class that you can implement to take information from one format into the one Simple Location understands. The plugin offers providers for:
- Geolocation - Looking up an address from coordinates or vice versa
- Location - By default this uses your browser to lookup your location but you can alternatively tap into a service to get your current location, perhaps from your phone
- Weather - Retrieves weather based on location or station ID
- Map - Provides maps for display
The plugin includes data files in its data folder, so these lookups don't need an online service:
- Weather stations for the Meteostat provider: Meteostat, licensed under CC BY 4.0. Only each station's location, name and the dates it has hourly data for are included.
- Airports: OurAirports, public domain.
- Airlines: OpenFlights, licensed under the Open Database License.
- Countries and regions: ISO 3166 data from php-isocodes.
Developers can refresh the station, airport and airline files with composer update-data.
- Weather Icons are used for most of the weather options.
- Font Awesome is used for the transportation icons.
- Simple Icons supplies the transportation brand icons.
Requires PHP 7.4, WordPress 6.2 or ClassicPress 2.7. The Bing providers and MapQuest elevation have been removed because their services were retired; if you used one, choose another provider in Settings. Many fixes to location visibility and permissions.
- Requires ClassicPress 2.7; tested with WordPress 7.1
- Remove the Bing providers and MapQuest elevation, whose services were retired, and stop calling retired MapQuest hosts
- Move HERE weather and maps to the current v3 APIs and fix Weatherstack, Pirate Weather, NWS, Meteostat, Visual Crossing, Xweather, GeoNames, Geoapify, Google, LocationIQ, Nominatim and Pelias parsing
- Add optional map-only API keys for Google, HERE, LocationIQ and MapQuest, Google URL signing, and serve Geoapify map images from the site
- Keep hidden locations out of ActivityPub, use the visibility a Micropub client sends, and honor location visibility in widgets, photos and archives
- Let authors and commenters manage the location of their own content, and check permissions on bulk actions and lookups
- Validate coordinates and location fields when saving, and from Micropub and Webmentions
- Use the post's timezone in sloc_get_comment_datetime(), and ignore invalid timezones instead of failing
- Calculate sun and moon times for the local date and name moon phases correctly
- Use the fallback weather provider when a provider can't serve a time, and cache past weather by hour
- Keep readings of 0 and convert units correctly
- Find airports and weather stations from small sorted indexes instead of large data files, and refresh the airport data
- Fix the map archive fatal error when no map provider is set
- Fix widget forms, wrappers and errors, and keep service responses and credentials out of error messages
- Escape output late and sanitize request input
- Give static map images alternative text and keep them within provider limits
- Fix PHP 8 deprecations
- Deprecate ifset(), ifset_round() and Simple_Location_Plugin::load_textdomain()
- Document all classes, functions and hooks, and add a test suite for WordPress and ClassicPress
- Checked for compatibility with latest version
- Remove live ability to use development sites
- Lock airport and timezone lookup behind optional user login requirement
- Remove ability for bulk update if the user does not have permission to do so
- Fix issues with Last Seen Widget
- Refresh data
- Identify short circuit logic that was not triggering
- Fix variable naming
- Toggle srcset to false by default due load
- Update weather providers to latest APIs where possible
- Fix text domain warning error
Older releases are listed in changelog.md.