Routes WordPress Plugin

Introduction and Installation


The Routes WordPress plugin allows you to add geographical route information to articles and pages in a WordPress blog, map the routes using Google Maps, and create elevation charts. To see it in action, check out Jennifer's List of Bike Trails.

On these pages, you can learn about how to install and use the Routes plugin. A quick list of its features:

  • Each post or page can have either a route or a single geographical point associated with it. Points in routes can included elevations and tag markers.
  • Enter the routes or points via addresses, typing in latitude/longitude, clicking on a map, importing a GPX file, or a combination, on the post/page editing screen.
  • Separate from the route, each post/page can have one or more points of interest (POI) [new in version 2.3.0].
  • Blog viewers see a Google Map of the route/point and POI on the post/page screen, with tagged points marked, as well as overview maps on category/index pages.
  • Set up custom markers for different types of points, have custom line styles for the routes [new in version 2.3.0], and use different starting map types for different posts [new in version 2.3.1].
  • Optionally, create and display elevation charts of your routes, and allow users to download GPX files containing the route points [download is new in version 2.3.1].
  • Search by exact city, state, country, or for the closest routes to a geographical point.

Installation and Setup

Requirements for using Routes

  • WordPress version 2.2 or higher
  • A Google Maps-compatible browser (most are) with JavaScript enabled for yourself and your viewers to see the maps. (Note that some Internet Explorer users may need to change their security settings in order to see maps and map features, and they may need to upgrade to version 7.0 or higher.)
  • 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).
  • 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 profiles and GPX imports or not.

How to install and set up Routes

  1. Download the plugin file (bottom of this page). You will probably need to change the name to Routes.tar.gz.
  2. Extract and upload the files: routes.php (the main plugin file) goes into wp-content/plugins, in your WordPress installation. (In WordPress 2.6 and later, it's possible to choose a different location for wp-content; if so, put this file in your customized location for plugins.)
  3. Optionally, localize Routes: If you are using a localized version of WordPress and also want the Routes admin/editing panels (and one or two error messages blog viewers could see when using proximity search) 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 "", where LOCALE is the name of the locale you are using for WordPress (such as "es_ES" for Spanish). The POT file for translating into other languages is provided in the Routes zip file.
  4. Activate the plugin from your WordPress administration panel (log in, click on "Plugins" in the top menu bar, and activate the "Routes" plugin by clicking on the link that says "Activate" to the right of the plugin name). If you need more detailed information on how to manage WordPress plugins, please visit the Managing Plugins page on the WordPress site.
  5. Check status and set options: 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. Then you can optionally change settings (some of the explanations may be confusing until you read the rest of this web page):
    • Language Code: You can enter a 2-letter language code, and if it is supported by Google Maps, the tool tips, map types, and other text on the map will show up in that language. Leave this blank to use English. You can also let Routes use the setting of your WordPress locale, by checking the appropriate box.
    • Map Choices: Google Maps has several different types of maps it can show, depending on what part of the world you are mapping. Check the boxes for which choices you want to offer your blog viewers, and choose a Default map type. As of version 2.3.1 of Routes, you can also choose a starting map type for each post, to override the default. The choice must be one of the map types you have enabled.
    • Map Features: Google Maps has several optional features that can be shown on your Google Maps, including a scale of miles/km. A map control that lets you zoom and pan the map is always shown as well, and Google Maps automatically chooses a control size appropriate to the size of the map you are displaying.
    • Full size control: As of Routes version 2.3.1, you can include a "Full Size" button. If a site visitor clicks the button, the map will zoom to fill up their browser window, and they'll have a "Normal size" button to zoom back. You can define the text to show in the button, or you can define an Icon (see below) and use the icon/shadow image as the button images.
    • Driving Directions: If you check the box, when a visitor double-clicks on a map, they will be given a choice of getting driving directions to this point or from this point. This will open up Google Maps in another window.
    • Icons and line styles [New in version 2.3.0]: Choose what type of icons and lines 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 sections below on icons and line types for more information.
    • Create elevation profile on save: Check this box if you want Routes to create elevation profile image files whenever you save a post with elevation information, and automatically look up elevations when you enter a route point by clicking on the map. 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.
    • 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 fiels will always use meters, however, since that is the GPX standard.
    • Height/Width of elevation profile: Enter the height and width of the elevation profile images to create. Recommended minimum values are 100 by 100 pixels. Note that this setting does not affect any elevation profile images you have already created -- you will need to edit existing posts and save them to create or re-create elevation charts.
    • Options for elevation profile: Enter red, green, and blue values (0 to 255) for the background color of the elevation profile images (defaults to white, 255/255/255), the line/text color for the axes (defaults to black, 0/0/0), the color used to fill the elevation profile chart (defaults to a blue color), and the color used for markers on the elevation chart (defaults to a red color, if you have the box checked that says to add markers). There are links at the top of the Routes Settings screen to a couple of web sites where you can look up RGB values for colors. Note that this setting does not affect any elevation profile images you have already created -- you will need to edit existing posts and save them to create or re-create elevation charts.
    After entering all the settings, click the "Update" button to save them.
  6. If you are planning to generate elevation profiles, 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.)
  7. Add Routes to your theme (separate page).

That's it! You're now ready to add geographical information to your posts or pages (separate page), and have it displayed in your WordPress site.

Setting up Custom Icons

As of Routes 2.3.0, you can create custom icons for your web site. To create a custom icon, visit the Routes Icons settings page. 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 separate page 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 (GIF files do not seem to work in some browsers in Google Maps).
  • 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 aggregate/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.

Setting up Custom Line Types

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 not 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.

Frequently Asked Questions (and answers)

  1. I am having trouble with Routes in Internet Explorer. What could cause that?
    First off, make sure you are using Routes 1.02 or greater, WordPress 2.2 or higher, have upgraded IE to 7.0 or higher, and have followed the installation instructions above. If that doesn't fix the problem, 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 (Google Maps uses JavaScript to display the maps, and Routes uses Google Maps). 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.
  2. 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.
  3. 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.
  4. 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 instructions for 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.

    For testing purposes, you can also try the Sandbox theme (see the theme modifications page). If Sandbox is displaying maps and your theme is not, then you have not followed all of the instructions.

    Also, display of Google Maps (which Routes relies on) in a web page is VERY 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
  5. 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 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.
  6. 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.
  7. I am using Routes in an area where Google Maps doesn't have mapping data, just satellite images. Is it possible to make Routes start in Satellite mode?
    As of Routes Version 2.2, there are options to define which type of maps to offer on your site, and which one to use by default. See the options section, above.
  8. What versions of WordPress is this plugin compatible with?
    Routes works with version 2.2 and above of WordPress. The latest version of WordPress that has been tested with this plugin is 3.0.
  9. How can I find out if there is a new version of the plugin?
    Subscribe to the RSS feed on the sidebar of this page, or check back on this page regularly to see if there is a new version. Note: The mechanism in WordPress 2.3 and above for automatic checking of version updates does NOT work with this plugin! It only works for plugins that are hosted on a particular WordPress plugin site, and this plugin is not hosted there. Sorry!
  10. 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 charts.
    • 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 for GPX format information.

Questions, Comments, and Bugs

The Routes plugin is provided free, with no warrantee and no guarantee of service or support. However, Poplar ProductivityWare welcomes your comments. So if you have questions about how to install or use the plugin, suggestions for how to make it better, or wish to report a bug in the plugin, please contact Poplar ProductivityWare or leave a comment below.

Please read and follow the instructions on these pages carefully before contacting Poplar ProductivityWare with questions, or leaving a comment. Especially with Internet Explorer, all of the theme modifications need to be done exactly as specified for Routes to work. Thanks!

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 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.


Pb with WordPress 3.1.2 with routes


Thank very much you for your plugin. I use it for several years without any problem. But after the upgrade of WordPress 3.1.1 into 3.1.2 my maps are empty (only Google mark). I have tried with your sandbox theme and it's the same.
Have you noticed this problem?
Thank you again.
A + +

PS : I use actualy your plugin Route 2.3.1 with Firefox 4.0, safari 5.0.5 and Chrome 11.0.696.57 on my Mac.

Haven't upgraded

Hm. I haven't upgraded yet -- I will need to test and see what might be happening.

It could be (a) an incompatibility between Routes and WordPress 3.1.2, or (b) a problem with another plugin running on your site or (c) either WordPress or another plugin creating HTML output that is not valid (Google Maps is very sensitive to non-validating HTML output). To test for (c), go to and put in your URL. To test for (b), try turning off other plugins.

Anyway, I will make some time to test out Routes with the new WordPress in the next few days and report back.

Sorry for any inconvenience!
-- Jennifer


Just a thank for your reply. I'll try with yours indications.
Have a good day.

GPX Help

Greetings! Love the plugin! I am trying to import a GPX file and I keep getting an error that says "No Points in GPX File" Here is a snipped I created using an online google maps gpx file builder.

here is the file, any ideas?

[file removed by editor]

GPX format...

The GPX format has several different possible types of GPS information it can contain. Your GPX file uses the "rte" type, but Routes only supports the "trk" path, because most GPS devices save "trk" files, and that is what Routes was designed to import.

You might be able to convert it to the other type using GPSBabel (see links above), or maybe the Google Maps gpx file builder can save a "trk" file? I'm not sure about that... I'll also add the ability to upload "rte" files to the list of future features of Routes, but right now it doesn't support that. Sorry!



Hi, I upload the gpx file into post but it is wider than my post body. Can I somehow set the default width of the map? THX! Klimas

GPX not related to width

The import of a GPX file is not at all related to the width of the map in your post. Please read the section of the documentation on theme modifications to see about widths.