Welcome:   Guest : United States : kms
Saturday April 19th 2014
API Index
My Trails Location Based Search API
The My Trails Location Based Search will return a list of shared trails and markers found in the My Trails database based on latitude and longitude and the appropriate information linked with each trail or marker using http get. Results are returned as xml.

To use the My Trails Location Based Search you will firstly need to register for an 'API Key'.
Click here and request your 'API Key' - It's free!

Service address

http://mytrails.com.au/service_location.php

Example get URL format

http://mytrails.com.au/service_location.php?apikey=<API Key>&latitude=<Latitude>&longitude=<Longitude>&radius=<Search Radius in Kms>&username=<User name>&password=<Password>&filter=<true>

Example get URL:

http://mytrails.com.au/service_location.php?apikey=12345678901234567890&latitude=-37.7524368&longitude=145.076019&radius=2&username=SampleUser&password=12345&filter=true

Process

You will need to send a http get to the service address with the required fields.

[ ] indicates your only options for this field

( ) indicates additional information about this parameter

apikey
latitude
longitude
radius (search radius in kms)
username (optional)
password (optional, case sensitive)
filter [true] (optional)

The optional username and password parameters will return ALL user's trails/markers - including 'not shared' and 'link only'.

The optional filter parameter will filter the search based on username.

Success

A successful response will be in XML format.

If successful the response will return nodes of <trail> and <marker> with information in each.

The xml will always show <trail>'s before <marker>'s in the list of xml

Example resonse:

<?xml version="1.0" encoding="UTF-8"?>
  <myTrails>
    <trail>
      <name><![CDATA[Sample Trail]]></name>
      <description><![CDATA[Sample Description]]></description>
      <owner><![CDATA[SampleUser]]></owner>
      <lat>-37.740822</lat>
      <lon>145.136719</lon>
      <externalLink><![CDATA[http://mytrails.com.au/trails.php?tid=1000000]]></externalLink>
      <filePath>/trails/1000000/1000000000.xml</filePath>
      <distanceKms>31.75</distanceKms>
      <terrain>Off Road Trail</terrain>
      <mode>Mountain Bike</mode>
      <views>140</views>
    </trail>
    <marker>
      <name><![CDATA[Sample Marker]]></name>
      <description><![CDATA[Sample Description]]></description>
      <owner><![CDATA[SampleUser]]></owner>
      <lat>-37.796441</lat>
      <lon>145.000262</lon>
      <externalLink><![CDATA[http://mytrails.com.au/location.php?lat=-37.79&lon=145.00]]></externalLink>
    </marker>
  </myTrails>

Errors

If unsuccessful you will see one or more of the following error messages:

'nothing returned' = the search returned nothing
'parameter missing: api key' = your api key url parameter is missing
'parameter incorrect: api key invalid' = your api key is incorrect
'parameter missing: latitude' = your latitude url parameter is missing
'parameter missing: longitude' = your longitude url parameter is missing
'parameter missing: radius' = your radius url parameter is missing

If you are having issues with the Location Based Search Service - contact My Trails by clicking here.

My Trails Client Upload API
The My Trails Client Upload service allows you to upload trails or markers to My Trails using http post.

To use the My Trails Client Upload API you will firstly need to register for an 'API Key'.
Click here and request your 'API Key' - It's free!

Service address

http://mytrails.com.au/service_upload.php

Example form

http://mytrails.com.au/test_service_upload.php

Process

You will need to post a web form with the form's enctype="multipart/form-data" to the service address with the required fields.

[ ] indicates your only options for this field

( ) indicates additional information about this field

Input fields of type="text" that need to be posted to the service are:

apikey
username
password (case sensitive)

name (trail or marker name)
description (optional)
share [0,1,2] (0=do not share,1=do share,2=link only:do not publish on any lists or search results of My Trails)

type [marker,trail]

if type = 'marker' you will need to post these input fields of type="text":


latitude
longitude

if type = 'trail' you will need to post these input fields of type="text":

terrain [Road,Bike Trail,Off Road Trail,Road / Trail Combo,Path,Water]
mode [Road Bike,Hybrid Bike,Mountain Bike,Walking,Hiking,Running,Watercraft]
returnId [true] (optional)

if type = 'trail' you will need to post this input field of type="file":

gpxfile (gpx format of less than 3Mb with a .gpx file extension or gpx file compressed with gZip: .gz)

Success

If successful the response will return 'success'

If successful and you have passed in the paramater 'returnId' the response will return 'success:trail id'.
(eg: success:1000000).

Errors

If unsuccessful you will see one or more of the following error messages:

'parameter missing: apikey' = your api key url parameter is missing
'parameter incorrect: api key invalid' = your api key is incorrect
'parameter missing: username' = your username parameter is missing
'parameter incorrect: username' = your username is incorrect
'parameter missing: password' = your password parameter is missing
'parameter incorrect: password' = your password is incorrect
'parameter missing: type' = your type parameter is missing
'parameter incorrect: type - [trail,marker]' = your type does not match either trail or marker
'parameter missing: name' = your name parameter is missing
'parameter incorrect: name - illegal characters detected - <characters>' = your name contains illegal characters
'parameter incorrect: description - illegal characters detected - <characters>' = = your name contains illegal characters
'parameter incorrect: trail name already exists for current user' = you have already used this trail name
'error: lat/lon returned no country' = the reverse geocode service returned no country for your start point / marker*
'error: lat/lon returned no region' = the reverse geocode service returned no region for your start point / marker*
'error: lat/lon returned no results' = the reverse geocode service returned no data for your start point / marker*

type = 'marker'
'parameter missing: latitude' = your latitude parameter is missing
'parameter incorrect: latitude (is not a number)' = your latitude is not a valid number
'parameter missing: longitude' = your longitude parameter is missing
'parameter incorrect: longitude (is not a number)' = your longitude is not a valid number

type = 'trail'
'parameter missing: terrain' = your terrain parameter is missing
'parameter incorrect: terrain - [Road,Bike Trail,Off Road Trail,Road / Trail Combo,Path,Water] '
    = your terrain does not match one of the options
'parameter missing: mode' = your mode parameter is missing
'parameter incorrect: mode - [Road Bike,Hybrid Bike,Mountain Bike,Walking,Hiking,Running,Watercraft]'
    = your mode does not match one of the options
'parameter missing: file' = your file parameter is missing
'parameter incorrect: file size [< 3Mb]' = your file is too large - files need to be less than 3Mb
'error: invalid xml' = the xml in your gpx file is invalid
'error: incorrect trail length [>0km/mi]' = the length of your trail is 0km/mi

If you are having issues with the Client Upload Service - contact My Trails by clicking here.

* Contact us if you continue to get this error
My Trails Client Register API
The My Trails Client Register service allows you to register a user at My Trails using http post or http get.

To use the My Trails Client Register API you will firstly need to register for an 'API Key'.
Click here and request your 'API Key' - It's free!

Service address

http://mytrails.com.au/service_register.php

Example get URL format

http://mytrails.com.au/service_register.php?apikey=<API Key>&username=<Requested Username>&password=<Requested Password>&emailaddress=<User's Email Address>

Example get URL:

http://mytrails.com.au/service_register.php?apikey=12345678901234567890&username=SampleUser
&password=12345&emailaddress=SampleUser@emai.com

Example form for post requests

http://mytrails.com.au/test_service_register.php

Process

You will need to send http post or http get to the service address with the required fields/parameters.

[ ] indicates your only options for this field

( ) indicates additional information about this field

apikey
username (between 3 and 20 characters)
password (between 3 and 20 characters)
emailaddress

Success

If successful the response will return 'success'

The successful user will recieve an email with their new details.

Errors

If unsuccessful you will see one or more of the following error messages:

'parameter missing: apikey' = your apikey parameter is missing
'parameter incorrect: api key invalid' = your apikey is incorrect
'parameter missing: username' = your username parameter is missing
'parameter incorrect: username - [length > 2 characters]' = your username needs to be 3 characters or more
'parameter incorrect: username - [length < 21 characters]' = your username needs to be 20 characters or less
'parameter incorrect: username - illegal characters detected - <characters>'
    = your username contains illegal characters
'parameter incorrect: username 'username' is already in use' = your username is already in use - choose another
'parameter missing: password' = your password parameter is missing
'parameter incorrect: password' - [length > 2 characters]' = your password needs to be 3 characters or more
'parameter incorrect: password' - [length < 21 characters]' = your password needs to be 20 characters or less
'parameter missing: emailaddress' = your emailaddress parameter is missing
'parameter incorrect: emailaddress - invalid' = your email address is invalid

If you are having issues with the Client Register Service - contact My Trails by clicking here.

My Trails Client Registration Check API
The My Trails Client Registration Check service allows you to check the validity of a username and password using http get.

To use the My Trails Client Registration Check API you will firstly need to register for an 'API Key'.
Click here and request your 'API Key' - It's free!

Service address

http://mytrails.com.au/service_registrationcheck.php

Example get URL format

http://mytrails.com.au/service_registrationcheck.php?apikey=<API Key>&username=<Username>&password<=Password>

Example get URL:

http://mytrails.com.au/service_registrationcheck.php?apikey=12345678901234567890&username=SampleUser&password=12345

Process

You will need to send http get to the service address with the required parameters.

( ) indicates additional information about this field

apikey
username
password (case sensitive)

Success

If successful the response will return 'success'

Errors

If unsuccessful you will see one or more of the following error messages:

'parameter missing: apikey' = your apikey parameter is missing
'parameter incorrect: api key invalid' = your apikey is incorrect
'parameter missing: username' = your username parameter is missing
'parameter incorrect: username' = your username is incorrect
'parameter missing: password' = your password parameter is missing
'parameter incorrect: password' = your password is incorrect

If you are having issues with the Client Registration Check Service - contact My Trails by clicking here.