| 开发者 | dshanske |
|---|---|
| 更新时间 | 2026年10月30日 20:02 |
| PHP版本: | 7.4 及以上 |
| WordPress版本: | 7.1 |
| 版权: | GPLv2 or later |
| 版权网址: | 版权信息 |
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:
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:
sloc_map_cache_max_age filter, and the storage directory with the sloc_map_cache_directory filter.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. 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:
example.com. Changes can take up to 30 minutes to take effect.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.
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.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).
example.com/*. Restrict the main token to your server's IP address.
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
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 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.
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.
Weather is looked up with up to three providers, tried in order: the weather provider, then the 2nd and 3rd under Fallback Weather Providers, for example your own station, a free service and a paid one. The first that has weather is used, and its credit is shown. A provider is skipped, without asking it, where it can't have weather: outside the country it covers, such as the National Weather Service outside the US; more than 10 km from your stations, for Custom Station and WeeWX; or for a time it has no weather for. If a provider fails with an error, the next one is tried. Geocoding, elevation and venues work the same way, with Fallback Geo Providers, Fallback Elevation Providers and Fallback Venue Providers, tried when a provider finds nothing or fails, such as when its quota runs out. Venues are searched for within the Venue Search Radius and listed nearest first. Maps have no fallback, because the map provider decides how your maps look.
Yes. A weather station, for example, may have no sensor for the conditions, snow or cloud cover. Choose the readings under Fill In Missing Readings in the weather provider settings, and Open-Meteo fills in whatever the provider didn't give: the conditions (summary and icon), snowfall, snow depth, cloud cover, the feels-like temperature, solar radiation, and, for about the last three months only, the UV index and visibility. The provider's own readings, including 0, are kept, and Open-Meteo is credited alongside it. A condition that only describes the sky, such as one a station works out from its sunlight sensor, is replaced when Open-Meteo reports rain, snow, fog or a thunderstorm. Tools > Weather Fill does the same for existing posts, in the background. Posts at the same place within a month share one request to Open-Meteo, whose free service allows 10,000 a day. It can be stopped and continued, and if Open-Meteo refuses, such as for its daily limit, it stops and says why. Locations are rounded to about a kilometer before they are sent; Open-Meteo's weather is for an area of one to eleven kilometers, so nothing is lost.
Yes. Plus Codes are the short codes for places that Google Maps shows, such as 87F6XR2P+WH. Enter one in the Plus Code field of the Location box and choose Lookup, and it replaces the location. A short code, such as XR2P+WH, needs the town or city after it, such as XR2P+WH Philadelphia. Plus Codes are decoded on your site; the town is looked up with your geocoding provider.
Yes. Add geojson to any feed address: /feed/geojson/ for your latest posts, /location/philadelphia/feed/geojson/ for a location's posts, or a post's own feed, such as /2024/07/01/a-post/feed/geojson/, for that post. Without pretty permalinks, add ?feed=geojson instead. Each post with a public location is a point, with its title, link, date and address. Posts whose location isn't public are left out. Pages with a feed link to it, so mapping tools can find it. The sloc_geojson and sloc_geojson_feature filters change what is included.
When a provider fails with an error you can fix, such as a missing or rejected API key, an exhausted quota, or one of your stations that can't be read or has stopped updating, administrators see a notice on the Dashboard and the Simple Location settings, and it is listed in Tools → Site Health. The notice can be dismissed, and the error clears by itself the next time that provider works.
To be notified elsewhere, such as on your phone, hook the sloc_provider_error and sloc_provider_error_resolved actions, which receive a one-line message.
By default, the location, with the weather, is added after each post's content, and the map after the content of single posts, or of every post with "Show Maps on Home and Archive Pages". A comment's location is added after its text.
To place the location yourself, declare support for it in your theme's functions.php. The location is then no longer added to the content:
add_theme_support( 'simple-location' );
Then show it in your templates, where you want it:
if ( function_exists( 'get_post_location' ) ) { echo get_post_location(); }
get_post_location() returns the location's HTML, already escaped, and nothing for a location that isn't shown. It respects the post's location visibility: a protected location shows its description without coordinates, and a private one shows nothing to visitors. Its second argument changes what is shown, for example get_post_location( null, array( 'weather' => false ) ) without the weather. The simple_location_display_defaults filter changes the defaults everywhere. Similar functions show the location of comments, users and terms: get_comment_location(), get_user_location() and get_term_location().
get_post_map() returns the map, for a public location. The map is still added to the content with theme support; to place it yourself, remove it after the plugin adds it:
add_action( 'init', function () { remove_filter( 'the_content', array( 'Geo_Data', 'content_map' ), 11 ); }, 2 );
The location is wrapped in a div with the class sloc-display, for styling. get_post_geodata() and get_post_weatherdata() return the raw data. Check the 'visibility' they return before showing coordinates.
For places other than a web page, such as email: get_post_static_map() returns the map as data (image URL, link, size, alternative text and credit) instead of HTML, and takes durable => true for image URLs that keep working, and dark, srcset and loading set to false for a plain image. get_post_weather_text() returns the weather as plain text, such as "72°F Clear". get_post_aqi() shows the air quality index with its US EPA category and color, such as a yellow "AQI 72 Moderate", or as plain text with array( 'style' => 'text' ).
Each user has a location in their profile, set under Users > Profile or with the user REST endpoint (see "How can I update the location of my user profile?"). The Last Seen widget shows it, and the weather widget can show the weather there. Two settings connect it with posts:
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. When your browser doesn't give its location, because it can't or you didn't allow it, the address you typed in the location box is looked up instead. Type an address, or the latitude and longitude, and look it up again. 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. Posting to /wp-json/sloc_geo/1.0/user updates the user associated with the credentials you provide to the REST API. Send the location in one of these ways:
latitude and longitude parameters, with altitude, speed and heading if you have them;geo parameter with a geo URI, such as geo:45.01,-75.44,20;speed and heading properties, on its own or as {"locations": …}.visibility parameter (public, private or protected) can come with any of them, or alone. Without an altitude, it is looked up, and the address is looked up from the coordinates.
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:
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.
Dawarich and GeoPulse are self-hosted location history services, which receive your location from apps such as OwnTracks or Overland. Choose one as the Location Provider in Settings, then each user enters their server's URL and API key on their profile. Dawarich's key is on its Account page. GeoPulse needs version 2.1.0 or later; create an API token with only the read scope. The key is never shown again after it is saved, and only the user, or someone who can edit them, can use their account. Your server must be reachable at a public address: WordPress refuses requests to local and private network addresses.
Use the [sloc_map] shortcode. It draws a map with a marker at each place, in the style of the archive maps, and each marker links to its post or image where the map provider allows.
[sloc_map] maps the post's attached images that have GPS data.[sloc_map ids="12,34,56"] maps those posts or images.[sloc_map points="39.9524,-75.1636|40.7128,-74.0060"] maps the given latitude and longitude points.[sloc_map track="_p~iF~ps|U_ulLnnqC"] draws a route, given as an encoded polyline, as a line. markers="ends" (the default) marks its start and end, and markers="none" draws only the line. Long routes are simplified to 200 points, keeping their shape.width and height set the map's size in pixels.
To make a route map without writing the polyline yourself, use Tools > Location Track. Choose a start and end time, and it gets your route from your location provider (Compass, Dawarich or GeoPulse), shows a preview of the map, and gives you the shortcode to paste. Points inside venues whose posts are private or protected, such as home, are left out.Yes. Like /map/ for a map, add /temperature/, /rain/, /snow/ or /weather/ to any archive, such as a year, category, author or location: for example /2025/temperature/. For a location, use /temperature/location/pennsylvania/ or /rain/location/pennsylvania/, as with /map/location/pennsylvania/.
/temperature/ shows a chart of the temperatures of the archive's posts, in your site's units, followed by a list of them./rain/ and /snow/ show a bar chart of the rain or snow in the hour before each post, in millimeters or inches, followed by a list of them. Only posts with some rain or snow are shown./weather/ lists each post with its weather icon, summary and temperature.
Only posts with weather are shown, and only when their location isn't private, as their weather isn't shown otherwise. All are drawn without JavaScript.
A theme can change any view with its own temperature-archive.php, rain-archive.php, snow-archive.php or weather-archive.php, as it can the map view with map-archive.php.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. Each marker on the map links to its post, with every map provider except TomTom, whose maps have no markers. The plugin chooses the area the map shows so it knows where each marker is drawn, and the links need no scripts in the page.
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.
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:
The plugin includes data files in its data folder, so these lookups don't need an online service:
composer update-data.