Simple Location

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?"

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?"

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 Map Style setting, under Map Settings, chooses a family: Standard, Light, Dark, Satellite or Terrain. Each map provider draws its closest style, so maps keep their look when you change providers. A provider without that kind of style, such as Geoapify for satellite, draws its standard style. Each provider also has its own style setting, with all its styles. It is empty by default, which uses the Map Style setting; choosing a style there uses that style instead. Sites that chose a provider style before version 6.1.0 keep it. A post can have its own style family too, chosen under Map Style in its location box, such as Satellite for a hike while the site's maps stay Standard. If the map provider has no style of that kind, the post's map uses the site's style, and the post keeps its choice for a provider that has one. A post with its own style other than Standard keeps it in dark mode. Theme functions take it as an argument too, for example get_post_map( $post, array( 'style_family' => 'satellite' ) ). Google's light and dark styles are its road map recolored with Google's silver and night styling. With Dark Mode Maps on, maps also have the provider's dark style for visitors whose system is set to dark mode. Browsers only load the one they show. For providers served from your site, the dark style is stored as its own image.

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. Stadia Maps maps are stored the same way when you enter a Stadia Maps API key. Your site then fetches them from Stadia's cacheable endpoint, whose images you may keep for as long as you have a paid Stadia subscription. Each map from the cacheable endpoint costs many more credits than a standard one (see Stadia's pricing), and each high-density copy and each refresh is a new map, so consider setting Refresh Stored Maps After to 0. Without a key, or with Serve Maps From This Site turned off, maps load from Stadia's standard endpoint, which may not be stored. Maps from your own custom map server (see the custom map provider below) are stored the same way, when it signs its URLs or needs no key. Maps the server marks as private, such as Stadia Maps, whose terms forbid caching, are never stored: visitors are sent to the server's signed image link instead. So are maps where the server had to draw its default map, which are asked for again after 5 minutes. With only a plain client key, the server marks every map private, so those maps are loaded from the server. Maps from your own TileServer GL server are stored the same way. It needs the full tileserver-gl build, version 4.6 or later; the light build can't draw static maps. Choose its style from the ones the server lists. Each location is a dot in the marker color, or set a marker icon from the server's icon folder to draw that instead. The credit under the map, when you choose it there, is the one the server gives for the style; the credit on the image is the server's own static attribution text, set in its configuration. Images are fetched by your site's server, so a TileServer GL on a private address, such as localhost, needs WordPress's http_request_host_is_external filter to allow it. 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).

Most weather providers' terms ask for a credit where their weather is shown, so weather looked up from a provider records which one it came from, and its credit is shown with it, linked to the provider. The Weather Credits setting, under General Settings, puts the credits next to the weather (the default) or once in the page footer. Open-Meteo requires its credit next to its data, so it stays there either way. Providers without a credit requirement have no credit: the US National Weather Service, whose data is public domain, and HERE, Visual Crossing, weatherstack and Pirate Weather, where no requirement was found. Weather saved before version 6.1.0, or entered by hand, doesn't record a provider, so it has no credit. Environment Canada's data is under the Open Government Licence – Canada, which asks for the source to be credited. OpenWeather and Weatherbit only require their credit on free plans. The plugin can't tell which plan a key is on, so it shows them; a site on a paid plan can remove them, or change any credit, with the sloc_weather_credit filter.

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, MapQuest and Mapbox 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.

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. Mapbox: Mapbox uses its token only for maps, and for listing your own styles in the settings. * Create a public token (starting pk.) with the default public scopes. Add URL restrictions for your site, for example https://example.com, and enter the token as the Mapbox Map API Key. Mapbox's default public token can't be restricted. * Listing your own styles needs the styles:list scope, which only secret tokens (starting sk.) can have. Enter that token as the Mapbox API Key. It is only sent from your server. The plugin never puts a secret token in a map image, so if the Mapbox API Key is a secret token and the Mapbox Map API Key is empty, no Mapbox maps are shown. * Mapbox checks URL restrictions against the referring page and refuses requests without one. Restricted maps may therefore not load in feed readers or email, or on a site whose referrer policy is no-referrer or same-origin. LocationIQ: LocationIQ tokens can be restricted by HTTP referrer (for maps) or by IP address (for your server's lookups). * If your account allows a second token, enter it as the LocationIQ Map API Key and restrict it by HTTP referrer to your site, for example example.com/*. Restrict the main token to your server's IP address. * Free accounts get one token, used for both maps and geocoding. LocationIQ doesn't say whether one token with both kinds of restriction accepts requests matching either, so leave it unrestricted, or test both maps and lookups after restricting it. TomTom: TomTom uses its key only for maps. In the TomTom developer dashboard, allow the key only the Map Display API, so a copied key can't be used for other products. TomTom's domain whitelist works through CORS, which browsers don't apply to images, so it may not stop others from using a copied key. MapQuest: MapQuest doesn't document a way to restrict a key. Use a separate key as the MapQuest Map API Key, so you can replace it without changing geocoding if it is misused. Stadia Maps: With an API key, Stadia maps are served from your site, so the key is never shown to visitors. If you turn off Serve Maps From This Site, leave the Stadia Maps API Key empty and add your site's domain under Authentication in Stadia's client dashboard instead: maps then load from Stadia without a key in the page. As with other domain restrictions, maps may not load where no referring page is sent. 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. It needs version 1.0.0 or later of the server. All the commercial static map APIs used assemble the pieces of a map from public tile servers, which

The Static Map Style setting lists the providers and styles your server offers, read from its query API. If the server can't be reached, it lists the ones every server offers without keys, and the settings page says why. Styles chosen before version 6.1.0 of this plugin are converted to their new names. The Stamen styles no longer exist, so they use your server's default map. Maps that need a key on your server (such as CARTO or Stadia, once the server has their API keys) need a client. Run php bin/clients.php add <name> on the server, then enter the name as the Custom Static Map Client ID and the signing secret it shows as the Custom Static Map Signing Secret, on the API settings page. Map URLs are then signed: they carry the client name and a signature, never the secret, so they are safe to publish. The plain client key also works (Custom Static Map Client Key), but it appears in every map image URL, so anyone who views a page can copy it. On map archive pages, the plugin asks the server where it draws each marker, and stores the answer, so each marker can link to its post. 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 the server's own limit (1280 by 1280 pixels unless the server changes it), shrinking larger maps to fit. To lower this, define SLOC_STATICMAP_MAX_WIDTH and SLOC_STATICMAP_MAX_HEIGHT in wp-config.php, or use the sloc_staticmap_max_size filter.