Routes WordPress Plugin – Jennifer Hodgdon's Personal Site

Introduction: Motivation, History, and Features

In 2010, my partner Zach and I decided to go on a bicycle tour in Europe. In order to share photos and stories with various friends and family members, we wanted to write a blog, and I thought it would be more interesting if we could show the details of our bicycle route on maps in the blog, ideally with elevation information. At that time I was familiar with both WordPress and Drupal, so I looked for a plugin or module that would let us display a route on a blog post — but all I found was plugins that would allow you to add one or maybe a small number of geographic points to a post. Since I was a web programmer, I decided to make my own WordPress plugin, which I called “Routes”, which is still in use on our blog, Jennifer and Zach’s Adventures.

The early versions of the Routes plugin had these features (which you can see in action on our blog):

Click on a map to add points to your route, while editing a WordPress post or page.
Import a GPX file (which you could export from your GPS device); since most GPX files have a lot of points, the import feature also allows you to reduce the number of points imported.
Look up elevations for points using an elevation lookup service.
Create an image with an elevation profile from the points.
Display elevation profile image and a Google Map of the route along with the post. You can also add a link to download the geographical information in a GPX file.
Add short pieces of text to some of the geographical points; these generate pins on the map that display that text if you click on them.
Add city and state/country information to geographical points; these are searchable and you can also display a list of the states or countries in your posts (similar to a tag cloud).
Display an overview map of all of the posts listed on an “index” page of your blog (such as the home page or a tag or date archive), with pins on the map to click on to take you to each post.

Later on, I was contacted by someone who wanted another feature: “points of interest”, which are places not on a connected route, also displayed as pins on the map. I added that feature for him, along with the ability to define what the pins looked like (you could have several pin types) and customize the color of the route lines.

In 2019, I modified the plugin to use the Leaflet mapping library and Open Street Maps instead of Google Maps. The motivation for this was that Google Maps removed the ability for small-traffic sites to use their maps for free, but it also allowed the elevation and map to display together, so you could scroll through the route and see exactly where the elevation went up and down.

Most WordPress plugins are available for download on wordpress.org, but I have chosen not to list my plugin there. The reason is that no one really ever reads documentation, and it is not possible to just activate Routes and have it work — you need to make some modifications to your theme and do a few additional things. So, if you’re interested in adding Routes to your WordPress site, please read and follow these instructions, and you can download the plugin at the bottom of this page.

Installation and Settings

Requirements for using Routes

WordPress. Routes originally worked with version 5; the plugin has been updated as new WordPress versions come out, and I’m currently using it with WordPress 6.8.2 as of 2025. I am not certain it would work with older versions of WordPress any more.
The WordPress Classic Editor plugin.
A JavaScript-capable browser (most are) to see the maps.
The PHP GD library installed on your web host, if you want to generate elevation profile images (most commercial hosts do have the GD library — it is pretty standard). You don’t need this if you are using the interactive elevation profiles.
The PHP XML Parser library installed on your web host, if you want to import GPX files (again, this is pretty standard).

Note that the Settings page (see below) will tell you if you have things set up correctly for elevation profile images and GPX imports or not.

Installation and Activation

Follow these steps to get the plugin installed and set up:

Install and activate the Classic Editor WordPress plugin (you cannot edit Routes information in the newer WordPress editor — at least not yet!). If you need more detailed information on how to manage WordPress plugins, visit the Managing Plugins page on the WordPress site.
On the Writing settings page in the WordPress dashboard, make the Classic editor the default.
Download the latest Routes plugin file (routes.tgz, at bottom of this page).
Extract and upload the files: they will go into a sub-folder “routes” in your wp-content/plugins folder (or wherever you normally put plugins).
Optionally, localize Routes: If you are using a localized version of WordPress and also want the Routes admin/editing panels to display in a language other than English, you will need to localize Routes. Routes uses the standard WordPress translation mechanism; the MO file(s) you create need to go into the WordPress plugins directory (wp-content/plugins) and be named “routes-LOCALE.mo”, where LOCALE is the name of the locale you are using for WordPress (such as “es_ES” for Spanish).
Activate the Routes plugin from your WordPress administration panel.
Check status: Click on “Options” or “Settings” (depending on which version of WordPress you are using) and then “Routes” to get to the Routes settings panel. (The Routes plugin may not be properly installed during plugin activation, but visiting this page will try to install the database tables again, and should fix most installation problems). Verify that the Status section says Routes is installed correctly; it will also tell you there if you can import GPX files and create elevation profile images. You can also change settings (see below).
If you are planning to generate elevation profile images, make sure your WordPress uploads directory (usually wp-content/uploads under your WordPress site directory, although you can change this in WordPress 2.6 and later) exists and is writable. (The elevation profile images will be saved in a sub-directory “routes” underneath that directory, which Routes will create.)
Modify your theme (see section below).

Routes Settings

Click on “Options” or “Settings” (depending on which version of WordPress you are using) and then “Routes” to get to the Routes settings panel. On this page, you can change various settings (some of these will make more sense after reading more of this documentation):

Icons: Choose what type of icons you want to use by default (you can override these settings on each post/page as well). There are separate icons for “index” maps (such as your blog’s home page or tag archive page), the start point of each route when a post is displayed on its own page (this point gets an icon so that viewers can tell which direction the elevation profile goes), and tagged points within a route. You can also create custom icons on the Icons settings page (see section below).
Line styles: by default, Routes uses a semi-transparent blue line to mark routes on aggregate/index maps (such as on your blog’s home page or a tag, category, or date archive page) and single-post maps. You can change the default line style for marking routes on the Routes settings page, and when you are editing a post, you can override the default values. The line style consists of three settings: color (given by web-color settings, such as #FF0000 for red), opacity (ranging from 0 for completely invisible to .5 for semi-transparent to 1 for completely opaque), and width (the line width in pixels). A completely invisible line gives you the opportunity to tag points and make an elevation profile without showing a route line on your map.
Use metric units for elevation: Check this box if you want Routes to use metric units (meters) for elevations when you look them up with the Lookup button and on elevation profiles. If it is not checked, Routes will use English units (feet). Exported GPX files will always use meters, however, since that is the GPX standard.
Look up elevations: Routes can automatically look up the elevation of a point after you click on the map when entering geographic information. It will try three different elevation lookup services in order to find the elevation. On the post/page editing screen, there are also ways to look up elevation in batches of 100 points and individually.
Interactive elevation charts: check the box to use the interactive elevation chart, which will be embedded in the map.
Create elevation profile on save: If you prefer, instead of the interactive elevation chart, you can check this box to have Routes create elevation profile image files whenever you save a post with elevation information. Note that this setting does not affect any posts you have already created — you will need to edit existing posts (making sure elevation is included) and save them to create or re-create elevation charts. There are several options for elevation charts; I recommend a size of no smaller than 100 by 100 pixels.

After entering all the settings, click the “Update” button to save them.

Custom Icons

You can create custom icons for Routes on your web site. To create a custom icon, visit the Routes Icons settings page (from the Dashboard, Settings > Routes Icons). For each icon, you will need to:

Enter an Administrative Name (which will show up in drop-down lists when you are doing something that needs an icon.
Optionally, enter a Legend Name. If you enter a Legend Name, then the icon will show up in your theme when you use the legend function (see section below on theming). If you leave it blank, that icon will not appear in legends.
Upload an image file and optionally a shadow image file. You can also enter the URL of these files instead of uploading them. If you are uploading, I recommend using PNG files.
Enter the size (height/width) of your image files and the “anchor point” (in pixels) relative to the upper left corner of the icon. The anchor is the point where the icon will be centered over the latitude/longitude on the map.
Click “Update icons” after editing an icon’s information or adding information for a new icon.

Once you create a custom icon, there are several uses for them:

On an index map (such as on your blog’s home page or a tag, category, or date archive page), each post is shown with a line from the start to the finish of the route, and an icon in the center. You can choose the default icon to use for this on the Routes settings page (see above), and you can override the default on each post when you are editing the post.
On a single-post map, the first point of the route is marked with an icon. You can choose the default icon to use for this on the Routes settings page (see above), and you can override the default on each post when you are editing the post. If you don’t want the first point of each route to be marked with an icon, you can create a transparent or blank icon on the custom icons page, and use that.
On a single-post map, each point of the route that you tag with extra information is marked with an icon (a visitor to your site can click the icon to see the extra information in a pop-up window). You can choose the default icon to use for this on the Routes settings page (see above), and you can override the default on each post when you are editing the post.
Besides route points, each post can have separate “Points of Interest” (POI) that are separate from the route. You can choose the icon for each POI when you create it on the post editing screen.

Theme Modifications

There are several modifications you will need to make to standard WordPress themes, in order to use Routes.

Important: Display of maps in a web page may be sensitive to the HTML in the page being valid. So if you are having trouble getting route lines or maps to display, please make sure your theme is producing valid HTML on the page that is having trouble. You can check the validity of HTML at validator.w3.org.

Modifications Needed for ALL Maps

There are several modifications you will need to do to your theme, in order to display any maps:

Routes adds JavaScript functions to your blog using the standard wp_head/wp_footer mechanism of WordPress. So, for Routes to function correctly, your theme needs to use this mechanism (most do). If your theme is non-standard, make sure it includes the following line somewhere between the HTML <head> tag and the </head> tag in every page that will display a map (usually this will go in the header.php file):
<?php wp_head(); ?>
The same goes for the footer. You’ll need to make sure that this is just before the closing <body> tag in your theme’s footer file:
<?php wp_footer(); ?>

Displaying Single Route Maps – Option 1

One main reason for using this plugin is to display a map of a route or points with the posts or pages you have added geographical information to (see the section below on geographical information entry to learn about how to add geographical information to a post or page). Routes only supports having one map per web page, so you don’t want to display the map corresponding to a particular post when you are on an archive page or any page that displays a list of posts (such as the blog’s home page). That is, you only want to display a single-route map when the user is viewing a single-post or single-page screen. Here’s one way to make this happen, if you always want the maps to be either entirely before or entirely after the text of your posts or pages. (There is another option in the next section, which does not involve modifying your theme.)

Make sure you have followed the “Modifications Needed for ALL Maps” instructions above.
Find the theme file used to display your post or page. Depending on your theme, for single posts, the file is either single.php (if it exists) or index.php (if it doesn’t). If you are adding geographical information to WordPress pages as well as posts, you will need to repeat these steps for the theme file used to display pages (which is either page.php, index.php, or a custom page template file).
Find the section of the theme file where the post’s (or page’s) content is displayed — it should say:
<?php the_content(); ?>
Note that in some themes, you may have to navigate to a different PHP file to find the content. For instance, if there is a line in your index.php, single.php, or page.php file saying something like this:
<?php require('post.php'); ?>
(or it could be “include” or “include_once” or “require_once” rather than “require”), then you would look in the file post.php to find where the content is printed.
Open the theme file you found in a plain-text editor.
Right below or above the content line, add the following lines to your theme file:
<?php if ((is_single() || is_page()) && function_exists( 'routes_map' )) { routes_map( get_the_ID(), 500, 400, "Text to print above map" ); } ?>
You can replace the 500 and 400 with a different width and height (in pixels) if you want a different-sized map, and you can leave out the text to print above the map by just entering “” with no text inside.
Save the theme file and upload it to your web server.
If you want maps on your pages as well as posts, repeat the steps above with your theme’s pages.php file, or custom page template file, if you have one in your theme.

Displaying Single Route Maps – Option 2

You can also get route maps displayed on single-post or single-page web pages using an alternate method, which allows you to put the maps anywhere you would like in your posts and pages. To do this:

Make sure you have followed the “Modifications Needed for ALL Maps” instructions above.
In each post or page, if you want a map to appear, put the following special function line into the body of your post or page:
[[routes_map( 500, 400, "Text to print above map" )]]
You can replace the 500 and 400 with a different width and height (in pixels) if you want a different-sized map, and you can leave out the text to print above the map by just entering “” with no text inside.

If you use this method for putting maps in your post, there are a couple of things to remember:

Maps will be omitted when you are on an archive page, or any other page that displays more than one page or post.
No map will be displayed in any post or page where you forget to put the special function line into the body of the post, even if you have entered geographical information for that post.
You cannot mix Option 1 and Option 2 for single route maps. Either modify your theme, or use the special function line, but not both.

Displaying Aggregate Route Maps

You can add an aggregate route map to your index pages, such as your tag archive pages and your blog’s home page. This makes it so that whenever WordPress is displaying a list of posts, if they have any routes associated with them, they will be shown on an index map. The map will allow them to pan and zoom (just like any map), and it has these additional special features:

Clicking on a marker or line in the map takes you to the corresponding post about that route or point.
Hovering your mouse over a marker shows you the name of the corresponding post.

Here is how to add aggregate route maps to your theme:

Make sure you have followed the “Modifications Needed for ALL Maps” instructions above.
Find the theme file used to display the archives you want to add maps to — see this article about the WordPress hierarchy of Theme files — such as index.php, category.php, etc.
Open your theme file in a plain text editor.
Decide where you would like the map to be. If you want it to be above the list of posts, then you need to find the beginning of the WordPress “Loop”, and insert just above it. If you want the map to be below the list of posts, then you need to find the end of the WordPress Loop, and insert just after it. To find the beginning and end of the Loop, read this article about the WordPress Loop. Note when reading the article that even if you are running a later version of WordPress, your theme may be based on an older version.
Insert the following lines into your theme, either before or after the Loop (but NOT inside the Loop):
<?php if ((is_archive() || is_search() || is_home()) && function_exists( 'routes_map_multiple' )) { routes_map_multiple( 500, 400, "Text to print above map" ); } ?>
You can replace the 500 and 400 with a different width and height (in pixels) if you want a different-sized map, and you can leave out the text to print above the map by just entering “” with no text inside. Also, if you want to have the map print for only some types of archive files, you might need to use other WordPress Conditional Tags. Note that “||” in the list above is PHP syntax for “OR”, so for instance if you only want the map to be printed on search and category pages, you would use the line:
if ((is_category() || is_search()) &&
Save the theme file and upload it to your web server.
Repeat the steps above for the other theme files that you want maps to appear on.

Note: This function only displays on the map the routes attached to the posts that are displayed below/above it on that particular page of results, so if you want more items displayed, you might want to change the option for “Show at most X posts per page” on the “Reading” screen under “Options” or “Settings” in your WordPress admin panel. You can set that option to the value -1 to make it display all posts no matter what.

Displaying Elevation Profile Images

If you generate elevation profile images instead of using interactive elevation charts, you can add the following lines to your single-post theme file to show the generated elevation profile chart (see the section above on single-route maps for information on how to find the right theme file and where in the file to insert the chart):

<?php if(( is_single() || is_page() ) && function_exists( 'routes_elev_profile' )) { routes_elev_profile( get_the_ID(), "Text for above chart" ); } ?>

You can replace “Text for above chart” with the text you would like to see above the elevation charts. If there is no chart for the post or page being displayed, neither the text nor any image will be shown.

If you want the elevation profiles on multiple-post pages (such as your monthly archive, blog home page, or tag archive pages), use the following in those theme files:
> <?php if( function_exists( 'routes_elev_profile' )) { routes_elev_profile( get_the_ID(), "Text for above chart" ); } ?>

Or, if you prefer, you can also use the post editor to put the elevation plots directly into your posts, from the Uploads or Add Media area of the post editing screen, once they have been generated (they are generated every time you save your post or page, with the same file name every time, if you have the option set to do that — see the section below on entering geographical information). If you decide to do that, it is best NOT to put the routes_elev_profile lines above into your theme, or you will end up with two elevation profiles on the screen. One note: In the Add Media dialogs, if you choose to make the image a link to the “attachment page”, you will have problems, because each time you save the post, it makes a new image, and it is saved as a new attachment. So either don’t make the image link anywhere, or link it to the image, and you will be fine.

Enabling Geographical Searching

Routes has the capability of searching by city and/or state/country (if you enter them in your routes — see the section below on entering geographical information). If your theme includes the default WordPress search form, and a user enters a search term, Routes will automatically search in the cities and states/countries you entered (as well as the post titles and text content).

You can also offer your visitors a specific city and/or state/country search. There are three ways to do this:

Add the “Routes Search” widget to your sidebar, and configure it.
Build your own search form, similar to the default search form in your theme. Add fields with name and ID equal to “routes_city” to search the City field of your routes, and “routes_state” to search the State/Country field of your routes.
Enter the following in your sidebar (or wherever in your theme you would like the search form to appear):
<?php if( function_exists( 'routes_search_form' )) { routes_search_form( "Keyword", "City", "State", "Search" ); } ?>
You can replace “Keyword”, “City”, “State”, and “Search” with the text that you want to use as the labels for the keyword field, city field, state/country field, and search button respectively. And if you would like to leave out one of the fields entirely, just enter “” for that field and it will not be printed.

Displaying the State/Country List

Routes also has a function to list the states/countries you have entered into your route points, with each state/country being a link. When a blog viewer clicks the link, they will be shown a list of all the routes that are in that state/country (up to your page limit) — just as if they used the search by state/country function described above. This list can be added to the sidebar (to show all states/countries you have entered) or to a post/page (to show the states/countries for that particular post/page).

To add the full state/country list to your sidebar (or wherever you want it in your theme), there are two methods:

Add the “Routes State List” widget to your sidebar, and configure it.
Insert the following lines where you want the state list to appear in your theme:
<?php if( function_exists( 'routes_list_states' )) { routes_list_states( " | " ); } ?>
As shown, a vertical bar “|” will be put between each state in the list. If you would like to have them on separate lines, use “<br />”. If you would like to have them separated by commas, use “, “.

Displaying the Icon Legend

If you are using custom icons and Points of Interest, you may want to display a “legend” that shows what each of your icons means. To do that, figure out where you want the legend in your “single.php”, “index.php”, or other theme file, and insert the following:
<?php routes_icon_legend(); ?>

Note that only icons that have a legend name entered will be shown in the legend.

Displaying a GPX Download Link

Routes can automatically add a link to each post/page that contains a route, so that visitors to your site can download a GPX file containing the route. To do this, insert the following in your “Loop”:
<?php routes_gpx_link(); ?>

You can also change the text shown in the link (which can contain HTML, etc.):
<?php routes_gpx_link('HTML or plain text to go into the link'); ?>

Advanced: Conditional Tags

If you are an advanced theme programmer, you might want to know about a “Conditional Tag” that Routes defines: routes_is_search() . This is like the standard is_search() conditional tag, but it also detects when the user has searched for a specific city, state, and/or country (or clicked on a state/country from the state list).

Entering Geographical Information

Once you have the Routes plugin installed and set up, as described above, you are ready to enter route information for your blog. Route information can be added to both posts and pages; it works the same for both, so if you want to add information to a page, follow the directions below and wherever it says “post”, substitute “page”.

First you need to find the Routes data entry section on the post editing screen (as noted above, you will need to be using the Classic Editor plugin):

Find a post that you would like to add route information to, or create a new post and enter a title and body.
Scroll down and find where it says “Routes Waypoints” near the bottom.
Expand the Routes Waypoints section by clicking on the “+” sign or arrow on the bar, if necessary.
At the top of this section, you can define which icons and line type you want to use for this particular post (to override the defaults).
Expand or hide groups of data entry lines, as necessary, by clicking on the “Show/hide rows 1 to …” links.

There are two types of points you can enter: “route points” and “points of interest” (POI). If you want to have a map, you need to enter at least one route point.

Route Points

Each route point has several fields of information you can enter:

Order (Required): An ordering number for the point — for instance, number the first point 10, the second 20, and so on. That way if you need to insert another point, you can number it 15 to insert it in between. (You can also use decimal numbers in the Order field, if necessary.)
City: City where your point is located. This can be used for searching by city (see theme section above).
State/Country: State and/or Country where your point is located. This can be used for searching by state/country (see theme section above).
Latitude and Longitude (Required): Routes are displayed on maps using Latitude and Longitude fields only, so these fields are required.

If you click on the “Show/Hide Extended Info” button above the list of route points, you will see an additional line of fields for each route point:

Tag: Extra information associated with this point. If you enter something here, blog viewers will see a marker in a single-route map at that point, and if they click on the marker, they will see the information you entered displayed in a map information window. This information can be plain text or HTML (which you can use for images, links, formatting, etc.). Also, if you have checked the box on the Routes settings screen to create elevation profiles, and the box that says to put markers on the elevation profiles, you will get a marker on the elevation profile corresponding to the marker on the map.
Elevation: You can look up the elevation of the entered latitude and longitude by clicking on the Lookup button, if one of the three elevation lookup web services encoded in Routes is working. You can also enter elevation values directly. Once you have looked up or entered at least two elevation values for a route and save the post containing the route, an elevation profile graph will be generated (if you have set the option telling Routes to generate elevation profiles — see the settings section above). If you forgot to enter elevations, or you imported a GPX file (see below) whose elevations are faulty or missing, you can look up elevations in bulk by using the “Look up 100 elevations” button. It looks up elevations in batches of 100 rows of information, so if you have more than 100 points in your route, you will need to click the button multiple times to update all the elevations.

There are several ways to get information into these fields:

Type information into the fields:
- It’s possible to enter just one point for a post or page. In that case, maps will display a marker at that point, rather than a route. If you enter at least two points, single-post maps will show a line connecting all the points in order, and aggregate maps will show a line from the first point directly to the last point, and a clickable marker with the post title.
- If you need more space, click on “Add More Input Lines”.
Use the map to enter points:
1. Click the “Refresh Map” button to show all the points you have already entered. (If the points are not in order, click “Save and Continue Editing” or “Save” instead to put them in order.)
2. Pan and zoom the map until the desired region is shown.
3. Click on the map where you want the next point to be. It will be entered in the list and shown on the map. If you have the option set to look up elevation automatically, the elevation of the point where you clicked will also be looked up automatically (just as if you had clicked the elevation lookup button, see above).
4. At this point, it is a good idea to go up and edit the Order, City, State/Country, and Tag fields (see above for descriptions). When you enter a new point, it is automatically given the previous line’s City and State/Country (if entered), and an Order value that is 10 beyond the previous Order, but you can edit those values. If you want to use City or State/Country searching, you will save yourself some time by entering the values after clicking on the first point, or whenever the City changes, so the rest of the City and State/Country values will be entered for you.
Import a GPX file. (Note that only GPS tracks in GPX format are supported. GPX “routes” and “waypoints” are not supported, only “tracks”, which is what most GPS devices create.) To do that:
1. Enter at least a post title on the post editing screen, and click “Save and Continue Editing” or “Save”.
2. Upload a single GPX file in the using the Add Media button.
3. Check the “import GPX” box in the Routes Waypoints section of the post editing screen, and if necessary, check the box saying that the GPX file has elevations in feet (this is unusual).
4. If the GPX file has a lot of points in it, you might want to enter a number to import just every 3 points, every 10 points, etc. in the box below. You might also check out the GPSBabel software, and use its “simplify” filter to reduce the points in your GPX file before uploading.
5. Click the “Save and Continue Editing”, “Save”, or “Save Draft” button on the post editing screen. Your GPX file will be imported and removed; the new points will come after any other points you had already entered on the map or by address lookup.

After entering some points, if you find you want to insert another point in the middle of the route, enter it in the bottom line (or click on the map), and then change the Order value to a value between the points where you want to insert the new point — you can use zero, negative numbers, and decimals. Next time you save, the points will be put in order.

After entering some points, if you find you want to delete a point, click on the checkbox in the “Delete” column, and next time you save, the point will be deleted. Or click on the point’s marker in the map, and it will be removed from the map and marked as Deleted in the list above.

To undo a deletion, uncheck the Delete check box in the list and click “Refresh Map”.

Note that if you have entered (or imported) a lot of points, some will be skipped rather than shown on the map, because maps with more than about 50 markers do not display well. If you want to delete points that are not shown, use the checkbox as described above.

Tip: If you hover over the marker, you will see the point’s order value, followed by its latitude and longitude, as an aid to finding it in the list above.

However you have chosen to enter your points, when you are done entering your points, click “Save” or “Publish”, and your points will be saved, along with the other post/page information. If you are generating elevation profiles, they are also regenerated every time you click “Save”, “Save and Continue Editing”, or “Publish”. Important: The WordPress “auto-save” function, which saves your post’s title and body periodically, does NOT save your Routes points! You need to click the “Save” or “Save and Continue Editing” button to make sure your points are saved.

Points of Interest

You can also have Points of Interest (POI) displayed on your per-post maps. These are points that are separate from the main route, and are displayed with custom icons (which you can set up on the Routes Icons settings page, see above).

POI have several fields of information you can enter:

Latitude and Longitude (Required): POI are displayed on maps using Latitude and Longitude fields only, so these fields are required. You can use the Lookup button to look up latitude and longitude by address (as described above), enter them directly, or click on the map. This works the same as when entering Route points (see above) — just make sure the option button is set so that when you click on the map, you get a POI instead of a Route point.
Text: If you enter something here, blog viewers can click on the marker, and they will see the information you entered displayed in an information window. This information can be plain text or HTML (which you can use for images, links, formatting, etc.).
Icon: Choose the icon you want to display this POI with, from the drop-down list. You can create custom icons for your site on the Routes Icons settings page (see above).

Frequently Asked Questions (and answers)

I am having trouble with Routes in Internet Explorer. What could cause that?
First off, make sure you are using the latest versions of Routes and WordPress, and a recent version of Internet Explorer (older IE versions may have problems). Check your browser’s security settings, and make sure JavaScript can be executed (for some reason, Microsoft has lumped this in with “Active Content” in some versions, and with “Scripting” in other versions). Finally, it could be that your HTML pages are not valid… for some reason, Internet Explorer is very sensitive to invalid HTML and JavaScript. So if you are seeing maps fine using a browser such as Firefox or Opera, and getting page errors or missing maps in Internet Explorer, check the validity of your WordPress output page using the W3C HTML Validator. If your page is invalid, fix your theme, posts, and pages until they produce valid HTML, and the problem with Routes should go away.
I have set the option to create elevation profiles, but they are not being created when I save my post. What could cause that?
There are several possibilities that you can look into:
- You have to have at least two points in your route with elevations entered in order to create an elevation profile.
- Routes uses WordPress’s file upload mechanism to save its elevation profile images, so if you are logged in as a user that does not have file upload permission, then Routes cannot create any elevation profile images. You can fix this by logging back in as the “admin” user, or any other user that has file upload permissions, going to the post edit screen, and saving the post again.
- Routes tries to save the files it creates in directory wp-content/uploads/routes (in WordPress 2.6 or later you can override the default uploads location, and if you do, Routes will put its files there instead of under wp-content/uploads). Routes will try to create the “routes” sub-directory if it does not already exist, but if your uploads directory does not exist, or if the web server does not have write permission on it, Routes will not be able to create its directory or save files there. You can fix this by creating the “uploads” directory and making sure the web server has write permission in it.
- Routes creates its elevation profile images using the PHP GD library, as well as a PHP XML library, so if your web host does not have the GD and XML libraries installed (most do!), Routes cannot create the images.
You can test most of this by trying to upload an image in the “Uploads” or “Add Media” section of your post editing screen. If that works, then the uploads directory is set up correctly and you have permission to upload. Then type in at least two elevation values (along with latitudes, longitudes, and point order values) for a post and click “Save and Continue Editing” or “Save”. If the elevation chart is created, you will see it in the “Uploads/Browse” section of the edit screen; if you are using WordPress 2.5 or later, it’s in the Gallery tab of the media button screens. If it isn’t created, but you can upload other images, go to the Options / Routes or Settings / Routes screen (depending on what version of WordPress you are using). There is a section near the top that says whether or not your web host has the software installed that will allow you to create elevation plots, and to allow you to import GPX files. There should be a message there explaining why it won’t work. Contact your web host and see if they can fix it.
Sometimes when I click on the map to add a point in the post editing screen, I get a route line to the new point, but no marker. Why?
If you have more than about 50 points in your route (maybe because you imported them from a GPX file), Routes will not show markers at every point. This is to avoid having the browser take a very long time to load. You can still delete the new point by clicking the Delete checkbox in the list above.
Maps don’t seem to be working at all, or if they are, no markers or lines are shown on them. Why could that be?
Probably you need to go back and read the section above on theme modification. You need to carefully follow all the instructions for “ALL maps”, and also either the instructions for “Single Route Maps” or “Aggregate Route Maps”, or both. There are several modifications that have to be made, and if they are not all done, Routes will not display maps correctly.
Also, display of maps in a web page may be sensitive to the HTML in the page being valid. So you might want to check that your HTML is valid, and fix any validation errors you find. You can check the validity of HTML at validator.w3.org.
I have uploaded a GPX file, but when I check the Import box and click “Save” or “Save and Continue Editing”, the file stays in the Uploads section and is not imported. What could cause that?
Go to the Settings / Routes screen. There is a section near the top that says whether or not your web host has the software installed that will allow you to create elevation plots, and to allow you to import GPX files. There should be a message there explaining why it won’t work. Contact your web host and see if they can fix it.
After installing and activating the plugin, when I try to use it I am getting an error that says “Table ‘wp_routes_waypoint’ does not exist.” (or something similar). Why?
wp_routes_waypoint (possibly with a different prefix other than “wp”) is the database table that Routes uses to store its point information. It is normally created when you first activate the plugin. However, if your WordPress installation does not have MySQL database permissions that allow it to create new tables, the table will not get created when you activate the plugin. If that is the case, you will need to update your MySQL database permissions. Contact your web host provider.
What versions of WordPress is this plugin compatible with?
Routes works with version 5 and above of WordPress, although I haven’t tested the latest version of Routes with older versions of WordPress. I recommend you use the latest WordPress and Routes versions, as they will work together (I personally use Routes, so if a WordPress update breaks it, I will generally fix it fairly soon).
How can I find out if there is a new version of the plugin?
Check back on this page regularly to see if there is a new version. Note: The mechanism in WordPress for automatic checking of version updates does NOT work with this plugin! It only works for plugins that are hosted on wordpress.org, and this plugin is not hosted there. Sorry!
What new features have been proposed or are under consideration?
- Add the ability to have multiple routes in a single post/page, maybe with a “prefix” field or a way to insert a break in the route.
- Add distances to the elevation chart images (interactive charts have distances).
- When importing a GPX file, be smarter about which points to save (e.g. dropping points in the middle of a straight line) rather than only having the ability to skip N points. Note: In the meantime, you might check out the GPSBabel software, and use its “simplify” filter to reduce the points in your GPX file before uploading.
- Make it possible to have multiple maps on the same page. For instance, on the blog’s home page, you might want to have a map for each post, or an aggregate map and a map for each post. Currently this is not possible to do in Routes (you can only have one map per page).
- Support the “rte” GPX file type (right now Routes only supports the “trk” format). See http://www.topografix.com/gpx.asp for GPX format information.

Version History for Routes Plugin

Version 3.0.2 – Fixed PHP warning when searching

Version 3.0.1 – Fixed elevation lookup, as lookup service URLs and API formats had changed. New links to plugin home page.

Version 3.0 – Updated to use Leaflet and Open Street Map instead of Google Maps. Some map features are no longer supported; new feature of interactive elevation charts is added. Note: If updating from older versions, see the theming section above to see what your theme needs, and take out other theme modifications you have from older Routes versions.

Version 2.3.4 – Change http URLs to https

Version 2.3.3 – Add Google Maps API key, because Google now requires it for new installations using maps.

Version 2.3.2 – Bug fixes regarding metric/English elevation units. Work-around for bug regarding activation not creating tables.

Version 2.3.1 – New features: GPX download, full screen button for maps, set map type default on a per-post basis

Version 2.3.0 – New features: custom icons and line styles, on a per-post basis; Points of Interest separate from route line

Version 2.2.11 – New features: button to look up elevations in bulk, street view control option, and ability to add markers to elevation profiles

Version 2.2.10 – Bug fix – GPX import can fail if you have inline images in your post. Also added messages to appear when you save a post.

Version 2.2.9 – Bug fix – when importing GPX files, the points were not appending to existing route points.

Version 2.2.8 – Bug fix – maps were not displaying in Internet Explorer 6 due to a JavaScript syntax error (not sure about other versions of Internet Explorer)

Version 2.2.7 – Bug fix – proximity search was not working in WordPress 3.0.

Version 2.2.6 – Updated to Google Maps API version 3 (no more API key needed, better printing, but no local search or overview map available). Better editing interface for faster loading when editing a post/page with a route. Elevation lookup is now done through Google maps (faster, more reliable, better coverage). Proximity search form looks up latitude/longitude automatically (no more lookup button).

Version 2.2.5 – Bug fix: when you do a generic keyword search in WordPress, Routes is also supposed to make it search in the city and state/country fields of any routes you have defined. This wasn’t working for recent versions of WordPress in Routes 2.2.4 and earlier versions; it now should work in all versions of WordPress.

Version 2.2.4 – Minor bug fix in states list, and add per-post functionality to states list. More status checks on settings page. Add option to use smaller map control.

Version 2.2.3 – Bug fix: list of states was including post/page revisions and unpublished posts/paged, fixed so it only includes states listed in published versions of posts and pages

Version 2.2.2 – Minor bug fixes and editing interface improvements. Add a class to legends on maps and elevation profiles.

Version 2.2.1 – Compatibility with WordPress 2.6’s ability to move the wp-content and upload directories (still compatible with older versions of WordPress).

Version 2.2 – New options for Local Search, map scale, overview map, map types, language, and driving directions. Make lines clickable on index maps. Bug fix: sometimes the post edit screen was showing too many markers and loading slowly.

Version 2.1.7 (limited release) – Fix minor internationalization bug. Fix for comma vs. period decimal points in numbers.

Version 2.1.6 – Updates for WordPress 2.5 (still works with earlier versions of WordPress)

Version 2.1.5 – Avoid loading Routes functions on most admin pages, for faster loading when Routes is not needed. Fix HTML error in Routes search forms. Add ability to automatically look up elevations when using map to input points. Add ability to place route maps in middle of body of post/page.

Version 2.1.4 – Added support for PHP 5 DOM library, which will allow PHP 5 users to import GPX files. PHP 4 is also still supported (if the XML DOM extension is installed, as before).

Version 2.1.3 – New feature: GPX import with reduced points. Bug fix: Routes searches now compatible with version 4.2 and above of MySQL (as is the rest of WordPress; previously Routes was using a MySQL 5.x feature in searches).

Version 2.1.2 – limited/internal release

Version 2.1.1 – Bug fixes: GPX import was always converting elevations to feet, state/country list was listing blank states. Also changed the post editing screen so that only about 50 markers are shown on the map — when showing more the screen took forever to load, or failed to load. And a few terms were missing from the internationalization files.

Version 2.1 – Add ability to import GPX files, “Delete All” button for points, and sidebar Widgets for WordPress 2.2 and above.

Version 2.0 – Add elevation profile charts, proximity search, and point tagging. Add ability to display aggregate maps with smaller markers. Markers on edit screen now show information to help locate them in the table above.

Version 1.02 – Fix Internet Explorer bugs. Note that if you are upgrading, some theme and core WordPress modifications are required, see instructions above.

Version 1.01 – Fix bug: strange characters appearing in marker hover text on aggregate maps. Minor improvements to admin editing interface. Remove markers at ends of single-route maps (now only prints a marker if it’s a single-point “route”, and prints a route line otherwise).

Version 1.0 – Initial Release.

Download

Download the Routes plugin, version 3.0.2 (routes.tgz archive file).

If you are updating from a version prior to 3.0, some map features have been removed. Read the theme modification section above and remove things from your theme that are no longer required or supported.