DEVELOPERS

Scout^TM for Apps

Meet the world's first HTML5 voice-guided, turn-by-turn navigation API for mobile developers and publishers. It's an effortless browser-based service and offers revenue sharing for US addresses.

Seamless one-click navigation with nothing to download or install.

Simple implementation with one line of code.

Premium navigation from any mobile website, application or email

The award-winning navigation technology that powers Scout for consumers on smartphones, computers and cars is now available to mobile developers and publishers with Scout for Apps. Scout for Apps is the first HTML5 service that allows you to offer users an exceptional, voice-guided turn-by-turn navigation experience with just one click to any address or location - for free. Including a Scout Drive-to button on your mobile content can help create a seamless experience that keeps users engaged, involved and coming back for more.

Easy implementation: Minimize development efforts with HTML5 for multi-platform support.

Better, more complete user experience: Bring your location-based content to life by helping users get to where they want to go.

Simple, convenient, and safe for your users: Provides real navigation. No cutting and pasting from one app to another. And Scout has automatic rerouting if a turn is missed.

Coming soon! Earn money, don't spend it: Enable ad-supported free navigation.

Need an ad-free version? No problem. Contact us to discuss how we can best help your business.

Scout for Apps Visual Tour

Third-party mobile applications, websites and emails often contain content with location that can be enhanced with voice-guided turn-by-turn navigation. All you need is a URL wherever you have location based content.

Here's an example of the product experience:

Third Party Site

Launch Screen

Navigation

Route Summary

Arrival Screen

Ad Landing Page

Requirements

Integration Requirements

An address or coordinates (latitude and longitude) to generate a route.

Platforms

iOS 4.0 +
Android 2.2+

URI Encoding

Tokens

Production keys

Certification Requirements

End User Requirements

HTML5 compatible browser enabled for location and audio.

GPS enabled Android or iPhone mobile device (see supported versions above).

Back to top

How to use the Scout API

Use these simple steps to integrate Scout for Apps with your location-based mobile content.

1. Get your test API key and token
2. Integrate Scout for Apps
3. Get your production API key and token
4. Submit to Apple or Google for launch

STEP 1. Get your test API key and token

Set up your account by joining the program.

Request your test API key by logging into your account and visiting the My API Keys page. This key should be kept very secure as it is your source for authentication.

Once you have your test API key, obtain a 'token' to use with the Scout for Apps API for security purposes. It doesn't expire, but it can be revoked if any fraudulent use is detected.

STEP 2: Integrate Scout for Apps

Display a Scout Button: Display one of the scout buttons near your location-based content, usually in search results or a landing page. See best practices below for examples. Choose from one of the button options:

Button Options:

iOS Static Buttons

Android Static Buttons

Note: Resize the Scout Button to fit your mobile site or app but don't change the aspect ratio or alter the button in any other manner.

Download the Scout Drive button images.

Add your code: Create the following URL as an action for the Scout button, or simply provide a link. The URL specification for integrating with the Scout API is described below. URI encode your token used in the URL.

http://apps.scout.me/v1/driveto?dt=<URI_encoded_address@lat,lon>&token=<URI_encoded_token>&name=<URI_encoded_name>

Arguments
Parameter	Description
token	Your token	Required. Must be URI encoded to work. E.g., if your token is "AQAAATS1a5IIf//", then the URI-encoded version will be "AQAAATS1a5IIf%2F%2F"
dt	Address	Street address. e.g., "950 De Guigne Dr." Street address should be combined with city/state or postalCode. See Example B. Required to display during navigation
	Lat , lon	DESTINATION COORDINATES: This field describes the latitude/longitude of the destination address.The latitude/longitude is specified as a String. For example: 37.373846,-121.999036 The lat/lon can be provided after the address followed by an "@" with an address (Example B) or without an address (Example C).
name	Name of the destination	Required to display during navigation. Every point of interest, whether it is a tourist attraction, event venue, or store, typically has a name. Passing this name will help Scout show the name to the user during navigation, upon arrival, and with their friends when shared.

Note: URI-encode ALL the parameters within this URL. Be sure to pass name and address for the optimal user experience. See best practices below for more detail.

Examples

A. http://apps.scout.me/v1/driveto?dt=950%20De%20Guigne%20Dr.%2CSunnyvale%2CCA&token=<URI_encoded_token>&name=SFO

B. http://apps.scout.me/v1/driveto?dt=3113%20MISSION%20COLLEGE%20BLVD
%2C%20SANTA%20CLARA%2C%20CA%2095054@37.388217,-121.983782&token=
<URI_encoded_token>&name=Marriott%20Hotel

C. http://apps.scout.me/v1/driveto?dt=37.36681,-122.00156&token=<URI_encoded_token>&name=Pizza%20Hut (this is not recommended)

Invoking any of the above actions will result in launching Scout for Apps in a browser screen similar to the following:

When users push the Drive button, they will launch the navigation mode with voice-guided turn-by-turn directions.

Running in a webview (optional)

If time spent within your app is a key metric for your business, consider embedding navigation to increase it. To maximize user safety, we allow a third party navbar with a maximum height of 44 pts. The remainder of the screen should be reserved for navigation to minimize driver distraction. To display the navigation experience that has been optimized for web view, add the following user agent string: TNS4A/1.0

Example:

Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_3_3 like Mac OS X; en-us) AppleWebKit/533.17.9 (KHTML, like Gecko) Version/5.0.2 Mobile/8J2 Safari/6533.18.5 TNS4A/1.0

We will also need a unique identifier to provide you with accurate session and unique user reports. This is especially important for developers licensing our ad-free service. Add a custom HTTP header, T-S4AID, with a unique id value generated by the native client, or add it as a parameter on the query string when invoking our API. It must be at least 32 characters long. This is similar to the device ID if you can retrieve the device id using the native client.

To provide the optimal user experience, we recommend the following:

1. Keep backlight on: to ensure the device remains on during the trip, enable backlight to "Always on" when webview opens, and disable when webview closes.

2. Support Portrait only mode: Disable landscape view for webview mode.

3. Use your back button for End Trip: Place a "back" button in your 44 pixel header.

STEP 3. Get your production API key and token

The test key and token you are provided are rate limited and are designed to only work with our testing servers. You will need to submit your application for review by Telenav to obtain your production key.

Review the Certification Guide to expedite getting your production keys.

Log into your account and request your production API key on the My API Keys page. You will be asked to submit a means to review your application as a link to a video, screenshots, or an actual application or website.

Once you have your production API key, obtain a "token" on the My API Keys page and update your code. If you have a back end server, we recommend storing tokens there to ease updating if necessary.

Required: You must obtain a production key before you submit your application to Apple or Google for certification.

STEP 4. Submit to Apple or Google for launch

Check the latest requirements to see if your application needs to be recertified by Apple or Google.

Be sure that you have updated your keys to production keys before submitting. If submission is not required, be sure you update your keys before launching.

Note: we recommend storing tokens on your back end server when available to ease updating if necessary.

Back to top

Code Samples

Scout for Apps code sample: iPhone

Scout for Apps code sample: Android

Scout for Apps code sample: Windows¹

¹For Windows Phone native apps, Scout for Apps requires that the browser control sends an additional HTTP header to
optimize the experience. This HTTP Header name is S4A-WV and its value must be set to TNS4A/1.0.

Back to top

Best practices

Pass destination name and address.

Where to place the Scout button on your mobile site or app.

Where to place the scout button in an email

How to use the Scout button with your existing Google Maps

Mitigating recertification from Apple or Google

Additional tips are available on our Forum.

Pass destination name and address

To provide more information to the user during navigation, you will need to send us the name and address of the destination for display in the navigation destination header, especially when using coordinates to generate a route. Here is what the header will look like:

Coordinates Only Name & Coordinates(Better) Name & Address(Best)

Where to place the Scout Button on your mobile site or app

Most mobile applications and websites have places of interest in a list and a landing page. The scout button can be used in either place. Here are some examples:

Where to place the Scout button in an email

If you send automatically generated emails to your users, consider integrating Scout for Apps with any location based content. This can include travel itineraries, email marketing to local businesses, and real estate notifications. Here is an example of how to use the Scout button in an automatically generated email.

You can also simply hyperlink the address in your email.

Using Google Maps

Many developers already use Google maps to display custom markers, multiple markers on a map, and marker labels. If you'd like to continue using Google maps, we recommend the following:

Step 1: Link to a location landing page from your Google Map InfoWindow.

Step 2: Place the Scout button on your location landing page.

Do not place the Scout Button on a Google Map. We recommend not placing the Scout button onto a marker Info Window. If you do not have a landing page for your InfoWindow, you may place a Scout button on the InfoWindow itself, using the following as an example:

Note: This button is slightly different than the buttons provided. Contact us by visiting our support page to obtain the button asset.

Mitigating Recertification

Not all code updates require recertification from Apple or Google. Always review the latest guidelines to verify when and if you need to recertify. Here are some examples of how you may be able to mitigate recertification.

Mobile Websites: They don't require any certification. If you have one, updating your mobile website may be the best place to start. This is also true for any dynamically generated HTML content within your native app.

Storing Tokens: Tokens are a means of protecting yourself from fraudulent use. If you use any back end server to dynamically generate content, we recommend storing your token there. If your token is hacked, you can regenerate one without having to recertify.

Back to top

SCOUT API DOCUMENTATION

Scout for Apps visual tour

Requirements

How to use the Scout API

Code samples

Best practices

<div class="telenavLink"><a href="http://www.telenav.com"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_logo.png"></a></div>
		{if app == 'scout' && curfunction == 'scoutBtn'}
				 <div class="navItem grayText"><a href="javascript:void(0)">Scout Drive Button</a></div>
        {else}
		<div class="navItem grayText"><a href="http://developer.telenav.com:80/sdkweb">Telenav Developers</a></div>
		{/if}
			{if app=='home'}
				{if page != 'home'}
					{if page == 'myaccount' ||page == 'password'||page == 'keys'}
				 	<div class="breadcrumbArrow"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_arrow.png"></div>
				 	<div class="navItem grayText"><a href="javascript:void(0)">Account</a></div>
				 	{/if}
					<div class="breadcrumbArrow"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_arrow.png"></div>
					<div class="navItem grayText"><a href="javascript:void(0)">
					{if page == 'apis'}APIs
					{elseif page == 'support'}Support
					{elseif page == 'myaccount'}My Account
					{elseif page == 'password'}Password
					{elseif page == 'keys'}API Keys
					{elseif page == 'login'}Log In
					{elseif page == 'join'}Join
					{elseif page == 'reset_password'}Reset Password
					{else}${page}
					{/if}
					</a></div>
				{/if}
			{/if}
			{if app!='home' && curfunction != 'scoutBtn'}
                {if page == 'apis'}
                    <div class="breadcrumbArrow"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_arrow.png"></div>
                    <div class="navItem grayText"><a href="dispatch.do?page=apis">APIs</a></div>
                {/if}
                
				<div class="breadcrumbArrow"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_arrow.png"></div>
				<div class="navItem grayText"><a href="scout?app=scout">
				     {if app == 'maitai'}Telenav Connect
				     {elseif app == 'scout'}Scout for Apps
				     {elseif app == 'share'}Telenav Share
				     {else}${app}
				     {/if}
				</a></div>
				
				{if page_current == 'home' ||app=='scout'}
				{elseif page_current == 'api' || page_current == 'platformdocs'}
				<div class="breadcrumbArrow"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_arrow.png"></div>
			    <div class="navItem grayText"><a href="scout?app=scout&page=home">Documentation</a></div>
			    {else}
	         	<div class="breadcrumbArrow"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_arrow.png"></div>
	         	<div class="navItem grayText"><a href="scout?app=scout&page=home">home</a></div>
			    {/if}
			    {if app != 'scout'}
			 	<div class="breadcrumbArrow"><img alt="Telenav" src="sdkweb/scout/image/breadcrumb_arrow.png"></div>
		 	    <div class="navItem grayText"><a href="javascript:void(0)">
		 	        {if app == 'geocoding'}
					 	{if curfunction == 'helloWorld'}My First Call
					 	{elseif curfunction == 'throttle'}Limit of Use
					 	{else}${curfunction}
					 	{/if}
		 	         {/if}
		 	        {if app == 'maitai'}
		 	        	{if curfunction == 'map'}Map API
		 	        	{elseif curfunction == 'navTo'}NavTo API
		 	        	{elseif curfunction == 'directions'}Directions API
		 	        	{elseif curfunction == 'search'}Search API
		 	        	{elseif curfunction == 'errorCodes'}Error Codes API
		 	        	{elseif curfunction == 'android'}Android Platform
		 	        	{elseif curfunction == 'rim'}RIM Platform
		 	        	{elseif curfunction == 'brew'}BREW Platform
		 	        	{else}${curfunction}
		 	            {/if}
                     {/if}
                     {if app == 'share'}
                            {if curfunction == 'login'}Login API
                            {elseif curfunction == 'shareAddress'}Share Address API
                            {elseif curfunction == 'sendToPhone'}Send To Phone API
                            {else}${curfunction}
                            {/if}
                     {/if}</a>
				</div>
				{/if}
			{/if}

First Name *

Last Name *

Company *

Title/Role *

Email *

Phone *

Password *

Confirm Password *

Select Product(s) of Interest *
Scout for Apps Telenav Connect Telenav Share
How do you intend to use this API(s)? *

How did you hear about us?

Please Specify:

Log In

ACCESS THE DEVELOPER NETWORK

Log in with your username and password to:

Join the Telenav developer community

Register as a member to:

Scout^TM for Apps

Scout for Apps Visual Tour