Simple Location

Contributors: dshanske
Tags: geolocation, timezones, maps, location, weather
Requires at least: 6.2
Tested up to: 7.1
Stable tag: 6.1.1
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.

Description

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.

Privacy and Data Notice

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.

If you choose readings under Fill In Missing Readings, the location of each post whose weather is missing them, including posts at a private location, is sent to Open-Meteo, rounded to about a kilometer, to fill them in.

Locations and Venues

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.

When duplicates are created, such as two localities for the same city, select them in the Locations list and choose Merge. On the next screen, pick the location to keep; the oldest is picked by default. You can merge only locations of the same kind: countries, regions or localities. Their posts and child locations move to the one kept, the others' names and codes are added to it so future lookups find it instead of creating the duplicate again, and the others are deleted, with their archive addresses redirecting to it.

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

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'. A venue can also set the visibility of posts made there with "Visibility of Posts Here", for example Private at home. It applies when a post's location is looked up in the editor, found in the background, sent by Micropub, or a check-in. A visibility chosen on the post, or sent by a Micropub client, still wins.

A venue is created when you check in, such as from a Micropub client, or with a bulk location lookup of check-ins. Before creating one, Simple Location looks for the venue you already have: the same place at a venue provider, the same website or page, or the same name close by. Checking in again from another provider adds to the venue you have instead of making a second one.

A venue's website is shown on its page. Its pages on other sites, such as OpenStreetMap, Google Maps, Foursquare or Wikipedia, are shown too when the venue's location is public, since a map link gives away where it is. You can edit both on the venue, under Website and Other Pages.

A new venue gets one of your venue types when one fits, such as Food for a restaurant, but Simple Location doesn't create types. When a venue has no type, the venue editor offers one, which you can add.

To combine duplicate venues, select them in the Venues list and choose Merge. On the next screen, pick the venue to keep; the oldest is picked by default. Its posts, photos, child venues, links and types then include those of the others, check-ins by the others' names or links find it, and the others are deleted, with their addresses redirecting to it.

What is kept from venue providers

Venue providers have different terms on what a site may keep. The plugin follows the maintainers' reading of them, below. It is your site and your decision: if you read a provider's terms differently, or aren't comfortable with them, choose another provider.

• OpenStreetMap Overpass, Nominatim, LocationIQ, Geoapify and your own Pelias server - the place's details are kept: address, phone, categories and links. OpenStreetMap data is under the Open Database License, which allows this with credit to OpenStreetMap contributors; a Pelias server's other sources, such as Who's On First and Foursquare's open places, are open data too.
• Google, Foursquare, HERE, TomTom and Stadia Maps - only the place's identifier and links are kept, such as its Google Maps or Foursquare link and its own website. The name is the one you checked in with, the coordinates are your own, and the address is looked up with your geocoding providers. Their phone numbers, categories and addresses are not stored.
• A check-in from a Micropub client that doesn't name a venue provider is your own, and is kept as sent.

A search for venues is remembered for 10 minutes, so a check-in app asking again from the same place doesn't use up your quota. This applies to the OpenStreetMap-based providers, Geoapify, Pelias and HERE, whose terms allow it, but not to Google, Foursquare, TomTom or Stadia Maps.

Weather

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

Stations allow for using a custom data source for weather data: a URL that returns the station's current conditions as JSON. When using the Custom Station provider for weather, it uses the nearest station within 10 km of your location, and the widgets can show any station by its ID. Readings more than an hour old are not used.

Each station has an ID, a URL, and optionally its latitude and longitude, which are read from the station when it gives them, and a credit with a link, shown with its weather.

The JSON should use the current conditions format, version 1, which the weewx-current-json extension writes for WeeWX stations:

{
  "format": "current-conditions",
  "version": 1,
  "time": 1761231600,
  "units": "metric",
  "station": { "id": "backyard", "name": "Backyard Weather", "latitude": 39.9524, "longitude": -75.1636, "altitude": 12,
               "attribution": { "text": "Weather from Backyard Weather", "url": "https://weather.example.com/" } },
  "observations": { "temperature": 21.5, "humidity": 61, "pressure": 1015.2, "windspeed": 3.58, "winddegree": 230, "rain": 1.27, "rainrate": 3.05, "code": 503 }
}

• time is when the observations were made, in Unix seconds.
• units is metric (degrees C, hPa, m/s, mm, mm/h, meters) or us (degrees F, inHg, mph, inches, inches per hour, miles).
• observations has any of the plugin's weather properties: temperature, humidity, dewpoint, heatindex, windchill, pressure, cloudiness, windspeed, winddegree, windgust, rain (in the last hour), rainrate, snow, visibility, radiation, illuminance, uv, aqi, and the pollutants pm1_0, pm2_5, pm10_0, co, co2, nh3, o3, pb and so2. Leave out what the station doesn't measure.
• code is a condition code, as listed in the weather settings, and summary is text; a known summary such as "Partly Cloudy" also gives a code. Without either, a station that measures solar radiation (or illuminance) gets an estimate of the sky by day: its reading is compared with what a clear sky would give at that time and place, from Clear Sky through Few, Scattered and Broken Clouds to Overcast. It isn't estimated with the sun low in the sky, or at night.
• station.attribution is the station's credit. A credit set in the station settings replaces it.

For a WeeWX station, install weewx-current-json and use the WeeWX weather provider instead. Its stations, under WeeWX Stations on the same tab, only need the URL of the file the extension writes, such as https://weather.example.com/current.json: the station's ID, name and location are read from it when you save. The extension also estimates the condition, such as rain or partly cloudy, from the station's sensors, a nearby airport, or the National Weather Service forecast.

JSON without format is read in the earlier format: the weather properties at the top level, in metric units, with wind as wind: { speed, degree, gust }, timestamp for the time, and N/A for missing values.

WordPress GeoData

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.

Providers

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, TomTom, and Stadia Maps, as well as your own map server: a custom Static Maps API server, or TileServer GL.
• Geocoding Providers take geo coordinates and look up the actual location/address for textual display. Geocoding Providers include Nominatim, which can use the public OpenStreetMap server, your own server or another host, Photon, HERE, MapQuest, Google, LocationIQ, OpenRoute and Geonames. They also support looking up coordinate for physical addresses. Photon needs no key, and you can use komoot's public server or run your own
• 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. Providers include Google, Foursquare, HERE, TomTom, LocationIQ, Geoapify, Stadia Maps, Nominatim, OpenStreetMap Overpass, which needs no key, and your own Pelias server.
• 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. Providers include GeoNames, Google, OpenRoute and Open Topo Data, whose public API needs no key and which you can also host yourself.
• 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 three self-hosted location history services: Compass, Dawarich and GeoPulse.
• Weather Providers retrieve weather data about your location and include OpenWeatherMap, Pirate Weather, Weatherstack, WeatherBit, HERE, Open-Meteo, MET Norway, Environment Canada and the US National Weather Service. Open-Meteo needs no key for non-commercial use, has historical weather, and can be self-hosted. MET Norway needs no key and covers the whole world. Environment Canada needs no key and gives the current conditions of the nearest Canadian city or town, within 100 km. HERE, Pirate Weather, 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. ** For weather services like the NWS, Environment Canada and your own stations, where coverage is not worldwide, up to two fallback weather providers can be set. They are tried in order when a provider has no weather. See the FAQ.

Frequently Asked Questions

What are the requirements to use this plugin?

Nothing else is needed to save locations. Looking up addresses, drawing maps, and adding weather and elevation use outside services, chosen under Settings > Simple Location > Providers (IndieWeb > Location when the IndieWeb plugin is installed). Some need no key: Nominatim for addresses, Open-Meteo, MET Norway and the US National Weather Service for weather, Open Topo Data for elevation, and your own weather stations. The others need an account, and an API key entered on the API Keys tab, where each service has its own section. See "How do I set up each service?"

Without a map provider, no maps are shown. Without a geocoding provider, addresses aren't looked up. Without a weather provider, weather isn't added.

Most services have a free allowance and charge, or stop, beyond it. The plugin only asks a service when you look up a location or publish a post, which usually stays well within it. You must follow each provider's terms. If a key stops working, or a quota runs out, administrators are told; see "How do I know when a provider stops working?"

How do I set up each service?

Sign up with the service, create an API key, and enter it in the service's section of the API Keys tab. Notes for each:

• Google Maps Platform - needs a billing account, and gives each API a monthly free allowance. In the Google Cloud console, enable the APIs for what you use Google for: the Maps Static API for maps, the Geocoding API for addresses, the Elevation API for elevation, and the Places API (New) for venues. Restrict the key to those APIs. For maps, see also "How do I protect my map API keys?"
• Mapbox - a public token (starting pk.) draws the maps. To list your own styles in the settings, enter a secret token with the styles:list scope as the Mapbox API Key, your username, and the public token as the Mapbox Map API Key; the secret token is never shown on your site.
• HERE - one API key for maps, addresses and weather.
• LocationIQ - one API key for maps, addresses and venues.
• Foursquare - venues, with a service API key from the Foursquare developer console. Place search is a Pro endpoint, billed per request after a small free allowance.
• MapQuest - one API key for maps and addresses.
• Geoapify - one API key for maps and addresses.
• TomTom - maps.
• Stadia Maps - static maps need a paid plan. The same key finds venues.
• OpenRouteService - one API key for addresses and elevation.
• GeoNames - addresses and elevation, with your username instead of a key. After signing up, enable the free web services on your GeoNames account page, or every lookup is refused.
• Pelias - addresses and venues from a Pelias server: enter its URL, and its API key if it needs one.
• OpenWeatherMap - the plugin uses One Call API 3.0, which needs its own "One Call by Call" subscription, with a payment card, even for the free daily calls. A key without it is refused.
• Weatherbit, Weatherstack, Visual Crossing and Pirate Weather - an API key each.
• Xweather - a client ID and client secret. People who share their personal weather station with PWSWeather.com get a free contributor account. You can choose whether personal weather stations are used.
• Meteostat - historic weather, with an API key from RapidAPI.
• Nominatim, Open-Meteo, MET Norway, Open Topo Data and the National Weather Service need no key. Nominatim's public server is for light use only; you can set your own, with the public one as a fallback. Open-Meteo is free for non-commercial use; commercial use needs a key. Open-Meteo and Open Topo Data can also use your own server.
• The custom map provider, custom station provider and WeeWX use your own servers; see their questions below. Compass, Dawarich and GeoPulse find where you are; see "How do I use Dawarich or GeoPulse?"

How do I add supp