Nearby Locations - Shortcode Usage

This page describes the usage and the attributes of the Nearby Locations shortcodes. You can use the shortcodes to display a list of locations nearby a specific point. Locations can be different objects, such as posts, users, and others. 

Nearby Locations Shortcodes

Basic shortcode

[gmw_nearby_locations]

This is the basic and global Nearby Locations shortcode, and you can use it with all the available object types. You can determine the object type using the "object" shortcode attribute, as described down this page.

Objects Shortcode

In addition to the basic shortcode, each object type might also come with its own shortcode. For example, the object type 'post', which displays nearby posts provides the shortcode:

[gmw_nearby_posts]

So, to display nearby posts, for example, you can use either [gmw_nearby_locations object="post"] or [gmw_nearby_posts]. Both shortcodes will produce the same results.

Shortcode Attributes

The shortcode attributes described on this page are global and will work with the different objects and different shortcodes. However, some objects might have additional attributes that are unique to them. Those unique attributes you can find in the details page of each specific object.

element_id

  • Description: The element ID is a unique ID that applies to the Nearby locations shortcode. The element ID is useful when you want to apply custom styling to a specific shortcode or make a use of the hooks provided by it. The element ID will help you distinguish between the different Nearby Locations shortcodes.
  • Usage: Use any numeric characters. Otherwise, the plugin will generate a random numeric value for you made up of 3 digits. Make sure you do not use the same element ID with more than one shortcode. As well make sure that the element ID that you choose is not being used by GEO my WP forms or other GEO my WP shortcodes/widgets. 
  • default value: random 3 digits numeric value. 
  • Example:
[gmw_nearby_locations element_id="18"]

object

  • Description: The type of locations that you would like to display. The Nearby Locations plugin provides the "post" object type only at the moment ( additional types might be available in the future ):
  • Usage: Enter the item type that you would like to display. Available types are "post" ( for the Posts Locator core extension ).
  • Default value: post. 
  • Examples:
[gmw_nearby_locations object="post"]

nearby

  • Description: the point which you want to display locations nearby. There are 4 options for  you  to choose from:
    • user: display locations nearby the user's current location. Note that the user's current location must be set via the Current Location shortcode/widget.
    • object: display locations nearby the object that is being displayed when viewing a single template file. For example, when viewing a specific post ( in a single post page ), then the shortcode will display locations nearby that post.
    • object ID ( numeric value): display locations nearby specific object by entering its  object  ID. For example, if the object is set to "posts"  then  you can enter a post ID to display locations nearby that post.
    • coordinates: display locations nearby specific coordinates by entering the latitude and  longitude  comma separated. For example 40.7127837,-74.005941.
  • Usage: Enter "user", "object", item ID ( numeric value ) or set of coordinates comma separated ( latitude,longitude ).
  • Default value: user.
  • Example:

Display posts near the user's current position:

[gmw_nearby_locations object="post" nearby="user"]

Display posts near post when viewing it in a single post page:

[gmw_nearby_locations object="post" nearby="object"]

Display posts nearby post with ID 18:

[gmw_nearby_locations object="post" nearby="18"]

Display locations nearby specific coordinates:

[gmw_nearby_locations object="post" nearby="40.7127837,-74.005941"]

units

  • Description: the distance units that you would like to use.
  • Usage: use "miles" or "kilometers". 
  • Default value: miles.
  • Example: display posts nearby the user's current location showing the distance in miles:
[gmw_nearby_locations object="post" nearby="user" units="miles"]

radius

  • Description: the radius to search for nearby locations.
  • Usage: enter a numeric value. 
  • Default value: 200. 
  • Example: Display posts within 300 miles from the user's current position:
[gmw_nearby_locations object="post" nearby="user" units="miles" radius="300"]

results_count

  • Description: the maximum number of locations to display.
  • Usage: enter a numeric value. 
  • Default value: 5. 
  • Example: display maximum of 8 posts within 250 kilometers from the post with ID 18:
[gmw_nearby_locations object="post" nearby="18" units="kilometers" radius="250" results_count="8"]

orderby

  • Description: the order of the locations.
  • Usage: enter the order-by value you would like to use. In addition to "distance" you can also order posts by any of the order-by items listed here. 
  • Default value: distance. 
  • Example: display posts ordered by the distance:
[gmw_nearby_locations object="post" orderby="distance"]

order

  • Description: choose between ascending or descending to order the list of locations.
  • Usage: enter ASC for ascending or DESC for descending. 
  • Default value: ASC. 
  • Example: display posts ordered by the distance in descending order:
[gmw_nearby_locations object="post" orderby="distance" order="DESC"]

show_map

  • Description: enable map showing the locations.
  • Usage: enter true/1/yes to display the map. 
  • Default value: true. 
  • Example: Display posts within 150 kilometers from the post with ID 24 and showing results on Google map:
[gmw_nearby_locations object="post" nearby="24" units="kilometers" radius="150" show_map="true"]

map_height

  • Description: the map's height.
  • Usage: set the map height in pixels or percentage ( ex. 250px or 100% ). 
  • Default value: 250px. 
  • Example: Display posts showing Google map with the map height set to 400px:
[gmw_nearby_locations object="post" show_map="true" map_height="400px"]

map_width

  • Description: the map's width.
  • Usage: set the map width in pixels or percentage ( ex. 250px or 100% ). 
  • Default value: 100%. 
  • Example: display posts showing Google map with the map height set to 350px and map width set to 300px:
[gmw_nearby_locations object="post" show_map="true" map_height="350px" map_width="300px"]

map_type

  • Description: set the map type.
  • Usage: the available map types are ROADMAP, SATELLITE, HYBRID, TERRAIN. 
  • Default value: ROADMAP. 
  • Example: display posts showing Google map with the map height set to 350px and map width set to 300px and the map type set to TERRAIN:
[gmw_nearby_locations object="post" show_map="true" map_height="350px" map_width="300px" map_type="TERRAIN"]

group_markers

  • Description: group nearby map markers using markers clusters.
  • Usage: use markers_clusterer if you'd like to group the map markers. Otherwise, set to false. 
  • Default value: markers_clusterer 
  • Example: Display posts showing Google and grouping nearby markers:
[gmw_nearby_locations object="post" show_map="true" group_markers="markers_clusterer]

map_icon_url

  • Description: use a custom image for the markers representing the locations on the map.
  • Usage: enter URL to the image that will be used as the map icon. 
  • Default value: URL of GEO my WP's default red map icon. 
  • Example: display posts showing the map and using a custom image as map markers:
[gmw_nearby_locations object="post" show_map="true" map_icon_url="https://maps.google.com/mapfiles/ms/icons/blue-dot.png"]

user_map_icon_url

  • Description: use a custom image for the map marker that represents the user's location.
  • Usage: enter URL to the image that will be used as the map icon. 
  • Default value: URL of GEO my WP's default blue map icon. 
  • Example: display posts showing the map and using a custom image as the user's map marker:
[gmw_nearby_locations object="post" show_map="true" user_map_icon_url="https://maps.google.com/mapfiles/ms/icons/blue-dot.png"]

show_locations_list

  • Description: Show/hide the list of locations.
  • Usage: set to true/1/yes if you'd like to show the list of locations. 
  • Default value: true. 
  • Example: Display posts showing the list of locations and Google map:
[gmw_nearby_locations object="post" show_locations_list="true" show_map="true"]
Example: Display posts showing Google map but without the list of locations: 
[gmw_nearby_locations object="post" show_locations_list="false" show_map="true"]

results_template

  • Description: choose the results template file. The plugin provides a few different results template files out of the box. You can as well modify or create your own results template files.
  • Usage: enter the folder's name of the results template file that you would like to use. Currently, there are 3 template files available: default, lightcoral and lightseagreen. 
  • Default Value: lightcoral. 
  • Example:
[gmw_nearby_locations results_template="lightseagreen"]

show_image

  • Description: display the object's image. An image can be the featured image of a post, for example.
  • Usage: enter true/1/yes to show the object's image. 
  • Default value: true. 
  • Example:
[gmw_nearby_locations show_image="true"]

show_distance

  • Description: display the distance in each location in the list of results.
  • Usage: use true/1/yes to show the distance. 
  • Default value: true. 
  • Example:
[gmw_nearby_locations show_distance="true"]

address_fields

  • Description: the address fields that will be displayed in each location in the results.
  • Usage: enter any of the address fields that you would like to display comma separated. You can choose a single or multiple address fields. The fields available are street, apt, city, state, zipcode, county and address ( for full address ). Otherwise, enter 0 to hide the address. 
  • Default value: address ( full address ). 
  • Example: display the city and state of each location in the list of results:
[gmw_nearby_locations address_fields="city,country"]

directions_link

  • Description: display the "Get directions" link in each location in the list of results. The link will open a new page with Google map showing the directions to the location.
  • Usage: enter any text that you would like to use as the "get directions" label or set to 0 if you wish to hide the get directions link.
  • Default Value: Get directions.
  • Example:
[gmw_nearby_locations directions_link="Get directions"]

show_random_locations

  • Description: display random locations if no nearby locations were found.
  • Usage: true/1/yes to display random locations. 
  • Default value: true. 
  • Example: search for posts within 200 miles from the user's current position. If nothing was found display random locations:
[gmw_nearby_locations object="post" nearby="user" units="miles" radius="200" show_random_locations="true"]

no_results_message

  • Description: the message that will display when locations were found ( and random locations is set to false ). 
  • Usage: enter any text that you would like to use as the "No results" message. Otherwise, set to 0 if you wish to hide the message. 
  • Default Value: Nothing was found nearby you. 
  • Example:
[gmw_nearby_locations show_random_locations="false" no_results_message="No locations were found"]

Related Articles