Contents - Index

Special Tags

You can use special tags in waypoint names, descriptions, custom URLs, and custom Programs. These special tags are converted to the corresponding information as described here:

%bear - Bearing from current centre point
%bgMap = Brithish grid - the 2 character grid map
%bgEast = British grid - the 5 digit easting value
%bgNorth = British grid - the 5 digit northing value
%blank - Blank or nothing
%bug = Travel bug status (notes)
%by   = Placed by
%c_Code = Full child code child waypoints
%c_Code1 = Child 1 character code - see child waypoints
%c_Comment = Child comments -  child waypoints
%c_Lat = Child Latitude see child waypoints
%c_Lon = Child Longitude - see child waypoints
%c_Name = Child name - see child waypoints
%c_Prefix = Child prefix - see child waypoints
%c_ShortName = Same as %ShortName but for the child waypoint name - see child waypoints
%c_Type = Child type - see child waypoints
%caches_xxxxxx = insert the value of  any "caches" table field (more information)
%children = see child waypoints
%centre = Current centre point
%code = Waypoint code (For example, the GCXXXX code)
%con = Container
%con1 = One letter indicating the container type (notes)
%correct = Corrected coordinate status (notes)
%county = County name
%custom_xxxxxx = insert the value of a custom field (more information)
%database = The current database name
%crypt = The coded hint (I.E. encrypted)
%datelf - Date last found)
%datepl - Date placed
%des = Cache description (Deprecated.  See note)
%dif   = Difficulty in full
%dif1 = Difficulty reduced to 1 digit (dif * 2 -1), so 1=1, 1.5=2, 2=3, 2.5=4, ...
%dif1a - Difficulty reduced to 1 character, so 1=1, 1.5 = A, 2=2, 2.5=B, 3=3, 3.5=C, 4=4, 4.5=D, 5=5
%dist - Distance from current centre point
%dnf = Did not find status (notes)
%drop2 = Same as %code, but drops the first two characters (notes)
%flag = User flag status  (notes)
%found = Found status. (notes)
%foundbyme = Found by me date
%gcid = Geocaching.com Cache number. (notes)
%GPX = Path to GPX file for current waypoint. Useful only for custom programs.
%hint = The decoded hint
%last4 = Last 4 found/not found logs (notes)
%lat = Latitude - 4 different formats to choose from (notes)  
%loc = Path to LOC file for current waypoint. Useful only for custom programs.
%lon = Longitude - 4 different formats to choose from (notes)  
%macro = this tag shows the result of running a macro (notes)
%mtag = Similar to %macro but optimzed for speed (notes)
%name = Cache name
%ownerID = Cache Owner ID
%ownerName = Cache Owner Name
%notGC = Tags after this tag apply only to non geocaching.com waypoints (see below)
%smart = GSAK "Unique Smart Name" (notes)
%shortname = Same as %smart but no guarantee of unique name (notes)
%status = Available, Unavailable, Archived
%state = State  (notes)
%ter  =  Terrain in full
%ter1 = Terrain reduced to 1 digit (dif * 2 -1), so 1=1, 1.5=2, 2=3, 2.5=4, ...
%ter1a - Terrain reduced to 1 character, so 1=1, 1.5 = A, 2=2, 2.5=B, 3=3, 3.5=C, 4=4, 4.5=D, 5=5
%typ  = Cache type
%typ1  = One letter indicating the cache type (notes)
%user = User Data.
%user2 = User Data2
%UserNote = The full text of the user note (minus the user log section)
%UserSort = The value of the user sort column for this cache
%UserLog = The full text of only the user log section within the user notes
%UTMZone - The UTM zone
%UTMEast - The UTM Easting
%UTMNorth - The UTM Northing

Note 1: The tags %name, %by, %con, %typ, %hint, %crypt, %user, %dif, %ter, %status, %state also support the format %tag=nn. Where nn is the number of characters to include. For example %typ=3 would only include the first 3 characters of the cache type, so that a "Multi Cache" would be translated to "Mul"

Note 2: %smart=nn is deprecated and supported for backwards compatibility only. I do not advise using it (more information)

%bug - If Cache contains a travel bug, returns Y, if not found returns N. This tag also support the syntax %bug=xx where the first character is used for "Has travel bug"  and the second for "No travel bug". For example, if you would prefer the %bug tag to show an asterisk when a cache has a travel bug and an exclamation when not, the syntax would be %bug=*!

%con1 - letters used are as follows: R=regular, L=large, M=micro, S=Small, V=Virtual, and U=unknown.  If the cache type is not stated, the letter used is U.

%correct - If waypoint has corrected coordinates, returns Y, otherwise returns N. This tag also support the syntax %correct=xx where the first character is used for "Has corrected coordinates"  and the second for "No corrected coordinates". For example, if you would prefer the %correct tag to show an asterisk when a cache has corrected coordinates and an exclamation when not, the syntax would be %correct=*!

%dnf - DNF logged returns Y, if no DNF returns N. This tag also support the syntax %dnf=xx where the first character is used for DNF waypoints and the second for no dnf. For example, if you would prefer the %dnf tag to show an asterisk for found and an exclamation for not found the syntax would be %dnf=*!

%drop2 - allows you to generate waypoints similar to the GCXXXX ones but without the needless GC at the front. For example, the cache GCAF12 which is a large multi cache, could be generated with the tags of %con1%typ1%drop2 to yield LMAF12. All the other tags used in the description format are available (and vice versa), but whatever tags you use, the total length of the resulting waypoint will be chopped off at the setting for "Maximum characters".

%found - Found returns Y, if not found returns N. This tag also support the syntax %found=xx where the first character is used for found waypoints and the second for not found. For example, if you would prefer the %found tag to show an asterisk for found and an exclamation for not found the syntax would be %found=*!

%flag - Checked returns Y, if not checked returns N. This tag also support the syntax %flag=xx where the first character is used for checked waypoints and the second for not checked. For example, if you would prefer the %flag tag to show an asterisk for checked and an exclamation for not checked the syntax would be %flag=*!

%gcid - This will yield the actual Geocaching.com number of a cache. Every cache code (the GCXXXX) code actually has a corresponding number. There is a rather convoluted algorithm to calculate this number, but suffice to say if you just use %gcid GSAK will do this calculation for you. This can come in handy when using it in custom URLs that require the Geocaching.com cache number rather than the cache code. An example of this is the watch a cache URL. If you would like to add the "Watch a Cache" customer URL the syntax would be http://www.geocaching.com/my/watchlist.aspx?w=%gcid

%lat - Latitude. This tag supports %lat=x where x is one of 4 formats to choose from:
D=Decimal degrees
M=Decimal minutes
S=Decimal seconds
U=UTM

Note, without the format specified the default is decimal degrees so the following are equivalent: %lat and %lat=D

%last4 - Last 4 found/not found logs. Found = F, Not Found = N, No log = 0. For example, if the latest log was a not found, the next a found, and there were no more logs this tag would return NF00. Notes are not included in the %last4 tag. 

%lon - Longitude. This tag supports %lon=x where x is one of 4 formats to choose from:
D=Decimal degrees
M=Decimal minutes
S=Decimal seconds
U=UTM

Note, without the format specified the default is decimal degrees so the following are equivalent: %lon and %lon=D

%macro - This special tag is very powerful as it allows you generate just about any information you want using a special tag. Basically this special tag will enable you to run a macro, and the macro must return a string that will be substituted for this tag. The macro must update the  system variable $_Special for this to work. For example, let us say that for some reason you want to show just the year (2 digits) portion of the last log date (and NL if there is no last log). Firstly create a macro with the following commands:
 

If $d_LastLog = [00000000]
  $_Special = "NL"
else  
  $_Special = DateToString($d_LastLog)
  $_Special = Substr($_Special,3,2)
endif

 
Now to display the last 2 digits of the Last Log year anywhere special tags are supported, enter this special tag: %macro="LastLog.gsk"
You can use other functions and variables in this macro but you must always update $_Special with a string value. You can have more than one %macro tag if you like (obviously each calling a different macro)

%notGC - The idea being that any tags before this one apply to geocaching.com waypoints and any tags after this apply to the rest. For example, if you used the following smart tags "%drop2 %ter1 %con1 %notGC %code"
This would mean that any waypoint that starts with "GC" will use "%drop2 %ter1 %con1" and all other would use "%code"

%smart - uses the calculated unique smart name from your database. For a complete overview of smart names please see the Smart Names topic. This tag also supports the form %smart=nn  (but not when used in the macro language, only in the GUI) where nn is the number of characters for the smart name. For example if you only want six characters in your smart name, your tag should be %smart=6  (note that %smart=06 also works). However, unlike other special tags that just return the first nn characters of data %smart=nn will force a recalculation of your smart names to this length and make this the default length for your database - see Database=>Properties. If you do not require unique names, then please use the more efficient %ShortName tag instead.

%ShortName - very similar to the %smart tag with the sole exception that unique names are not guaranteed. This tag is far more efficient as there is no re calculation of the database if you change the length of your short names. This tag also supports the syntax %ShortName=nn

%typ1 - letters used are as follows: T=traditional, M=multi, B=letterbox hybrid, C=CITO, E=event, L=locationless, V=virtual, W=webcam, O=Other, G=Benchmark, R=Earth, I=Wherigo and U=mystery/Unknown.

Anything else is left untouched.  Please note that the tags are not case sensitive.

%custom_xxxxxx - Get the value of a custom field where xxxxx is the custom field name you want to use. This special tag can be used any place other special tags are used and should enable a quick and easy way to include custom information in many areas of GSAK.Without this special tag you would be restricted to using %macro or %mtag to fetch the corresponding information. Note: This special tag also supports the common format %Custom_xxxx=nn where nn is the first nn characters of the value of the custom field fetched.

%caches_xxxxxx - This special tag is very similar to the %custom_xxxxxxx special tag above but applies to the "CachesAll" table. Hence giving you access to all the variables  (in the "CachesAll" table) now and in the future. This tag should be used in preference to fetching the same information via the %macro= or %mtag= special tag as it is much faster.

Note: The special tag %des is provided for backwards compatibility only; use %name instead.  Earlier versions of GSAK used the term "cache description" to mean "cache name".  However, this caused confusion with the actual cache description.  GSAK now uses the terms "cache name" and "cache description", consistent with their intended meanings.  Therefore, the special tag for the cache name has been changed to the more mnemonic %name.  Although %des still expands to the cache name at this time, there is no guarantee that this will always be the case.  You are strongly recommended to use %name in all new applications.

%mtag - First introduced in version 7.7.2, this special tag is very similar to %macro, but under the covers is has changed significantly to be optimized for exports.

The mechanics of using this special tag is virtually the same as for %macro. Basically this special tag will enable you to run a macro, and the macro must return a string that will be substituted for this tag. The macro must update the  system variable $_Special for this to work

First some background. The %macro tag is very powerful, but the Achilles heel of this tag is the performance hit of using it. Specifically, this mainly becomes an issue when used in exports. The problem is that for every record in the database we suffer the overhead of initializing (including the pre processor), running, and then finalizing the macro. This overhead can be significant and all adds up when processing many records.

The %mtag takes a different approach. GSAK will transparently convert your macro to loop through the current database and run this macro *before* the export starts. It stores the results in memory which are then "looked up" when the export is run. This means the macro is only ever run once and we only suffer the overhead once.

This tag does not completely replaced %macro (it is still needed in other places like custom urls) and does come with some caveats:

1. Only supported in export dialogs that have input fields that support special tags
2. Only 1 %mtag= supported per Parent section and only 1 %mtag= supported per child section (%macro= allows unlimited)

For example, this use of the special tag in any "waypoint name box" would be fine
 

%mtag="MacroA"%Children%mtag="MacroB"

 
However this would not:
 

%mtag="MacroA"%mtag="%MacroB"%Children%mtag="MacroC"

 
The thrust of new tag is to speed up the use of macro calculated information when processing multiple waypoints. All exports are the primary target for the use of this tag. We have established there is significant overhead opening/closing macros, so it doesn't make sense to allow for multiple macros here (not to mention the complexity). If you want more information added you should be able to just change the macro to include the extra information, rather than having to run an extra macro.

You can still use %macro with (or without) %mtag but this would negate the speed gains.

Taking a simple example of doing a GPX export where we want the CacheType to show after the code. Using the universal tag macro  you would place the following in the "Waypoint Name box"
 

%code%mtag="tag?CacheType"

 
Previously you would have used
 

%code%macro="tag?CacheType"

 
Doing this export on a test database of 3000 caches with 5 logs per cache, the time taken on my test machine (Win 7, 2.2 ghz, dual core, 2gb ram):

Using %macro= 2mins 40 secs
Using %mtag= 12 secs

Your mileage may vary. Testing done thus far tends to indicate the new %mtag is always faster, but the speed increase is less spectacular on newer hardware (in some cases the speed gain being very modest). The amount and composition of code in the macro also seems to have a bearing on the ratio of speed increase.

Also note that when you use the new %mtag, you will see a status box pop up while the macro is iterating through the database and calculating the values. This is mainly just to visually let you know of the progress.