Before an application tries to use the app2app interface, it should perform application discovery to ensure the Navigation application is installed and the device and can handle the command.
|Product name||URL scheme||URL identifier|
Use the UIApplication::canOpenURL method to check for availability of a URL scheme.
The discovery code needs to try canOpenURL with the schemes mentioned in the table until it finds one that can be used.
The following sample code checks to see if gokivonavigator is available.
NSURL* url = [NSURL URLWithString:@"gokivonavigator:app2app"];
BOOL available = [[UIApplication sharedApplication] canOpenURL:url];
Invoking the Gokivo API
Calling iPhone applications pass a URL, an optional credential, and a query string to the API to invoke Gokivo.
Use the function UIApplication::openURL
NSURL *url = [NSURL URLWithString:@"gokivonavigator:app2app?version=1.0&credential=123&commands=M&lat=33.67972&lon=-117.73668"];
[[UIApplication sharedApplication] openURL:url];
The query portion of the URL consists of "field=value" pairs separated by an ampersand (&).
<field1>=<value1>&<field2>=<value2>&.....<field n>=<value n>
Note: URLs must be escaped in accordance with RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax.
Passing the URL to the API
Gokivo registers a custom URL scheme handler. The application to application API is based on the ability of an iPhone application to register, so it can respond to such URLs. The open URL method launches Gokivo and passes the URL containing the query string.
The following code snippet shows how an iPhone application requests Gokivo services by means of the application to application API:
NSURL *url = [NSURL URLWithString:@"gokivonavigator:app2app?version=1.0&commands=N&street=43%20W%2057th%20St&city=New%20York&state=NY&postal=10019&country=USA&lat=40.76351&lon=-73.97530"];
[[UIApplication sharedApplication] openURL:myURL];
Gokivo generates an error and quits after encountering a problem with a URL query passed by the API. The following list shows the typical causes of errors:
Requesting Navigation to a Destination
All navigation requests passed by the application to application API must specify a destination coordinate pair. If the coordinate fields are missing or assigned incorrect values, the URL request will fail. All address fields are used for display purposes only and are not used to determine the location of a destination.
The credential field is currently included for tracking purposes only. Gokivo accepts URLs without credentials. But, if a credential is specified, it must be valid or the navigation request fails.
Note: TeleCommunication Systems reserves the right to restrict the use of the application to application API to users with valid credentials.
API Query Fields for Navigation Requests
The following table describes the query commands passed by the application to application API to launch Gokivo and navigate a route to a specified destination from the current location.
|version||API version, this field is required for all URL queries. Set to 1.0 (version=1.0).|
|credential||App2App user credential. This field is required for forward compatibility. Please contact TeleCommunication Systems to obtain an App2App credential for use by your application.|
|commands||"N" – Navigate to a destination from the user's current GPS position.
Note: The value N must be uppercase.
Required for all URL queries.
|name||The name of the place.|
|street||The number and name for the street address.|
|xstreet||If the destination address is an intersection, this field contains the cross street.|
|city||The city for the address.|
|county||The county for the address.|
|state||The two character state abbreviation for the address.|
|postal||The ZIP Code or Postal Code for the address.|
|country||The ISO 3-letter country code for the address.|
|lat||Latitude of the location. At least 4 decimal places of accuracy are required for accurate placement. Applications should supply 6 decimal places for the best accuracy.
Required for all navigation requests.
|lon||Longitude of the location. At least 4 decimal places of accuracy are required for accurate placement. Applications should supply 6 decimal places for the best accuracy.
Required for all navigation requests.
|navroutetype||Type of route to create for a trip, which can be one of the following:
|navavoid||Road features to avoid while routing. Which can be one or more of the following:
Use empty string to specify no avoids.
|navvehicletype||Navigation mode to use for a trip, which can be one of the following:
|navshow||Type of optional content to display during navigation. One or more of:
|navtraffic||Specifies the way traffic will be used to generate the route. One and only one of:
Example Navigation Queries
The following examples show typical URL requests that are passed by the API to launch Gokivo and create a route to a specified location.
Navigate to Named Place: Marriott Hotel at John Wayne Airport
Navigate to Coordinates: 33.67972, -117.85092
Navigate to an Address: 6 Liberty, Aliso Viejo, 92656 USA (Avoid Toll Roads)
Navigate to an Intersection: Del Mar Heights Rd and Carmel Canyon Rd, San Diego, CA 92130 (Avoid Highways)
Navigate to a Place in a Plaza: Jamba Juice at Del Mar Highlands Town Center
Navigate to an Airport: LAX Airport (Easiest Route)
Navigate to a City: San Francisco (Truck)
Navigate to a Zip Code: 92656 (Car)
Gokivo Application to Application API
Thank you for your interest in the TeleCommunication Systems Gokivo® Application to Application Programming Interface (the “Gokivo API”). The Gokivo API can be called by applications running on an Apple® iPhone™ to invoke Gokivo to provide navigation and map services. iPhone applications use the Gokivo API to pass location information to Gokivo in the form of a URL query. Gokivo services use information from the query to create a navigational route to a destination or show a map that includes a location.
"User Application" shall mean the application(s) that you use with the Gokivo API.
"Integrated Application" shall mean the User Application as modified by the Gokivo API.
"Gokivo Application" shall mean the TeleCommunication Systems location based services application(s) commonly known as Gokivo® which includes a client application for wireless devices as well as a server application.
2. Usage and Requirements.
a) to use and copy the Gokivo API to develop and enable the User Application to interface with, and receive and provide data to, the Gokivo Application only, for development purposes and for commercial use of the Integrated Application; and
b) to provide certain data to the Gokivo Application and receive certain data from the Gokivo Application, both during development and commercial use of the Integrated Application.
c) You may not transfer these licenses (2.1 a-b above) and these licenses cannot be sublicensed. You are solely responsible for all costs and expenses regarding the development of the Integrated Application. This is NOT a license to copy or distribute the Gokivo Application.
d) You grant TeleCommunication Systems a limited, non-exclusive, worldwide, royalty-free license to provide certain data to the Integrated Application and receive certain data from the Integrated Application, both during development and commercial use of the Gokivo Application during operation of the Integrated Application.
Attribution. You shall include the following text in the "Legal Notices," "About Box," or other similar location in the Integrated Application. "Gokivo®, TeleCommunication Systems™ and their logos are registered trademarks or trademarks of TeleCommunication Systems, Inc. Certain software or technical information in this product is provided by and licensed from TeleCommunication Systems, Inc., Copyright TeleCommunication Systems, Inc. © 2000 - 2013. All rights reserved."
Remedies You acknowledge that damages for improper use of the Gokivo API or Gokivo Application may be irreparable; therefore, TeleCommunication Systems is entitled to seek equitable relief, including but not limited to preliminary injunction and injunction, in addition to all other remedies, without the posting of a bond.
TeleCommunication Systems. Except for the limited license granted to you herein, all right, title and interest in and to the Gokivo API and the Gokivo Applications, including the concepts and technology inherent in them, and the TeleCommunication Systems trademarks, copyrights, patents, trade secrets and other intellectual property, are, and at all times shall remain, the sole and exclusive property of TeleCommunication Systems.
4. Third Party Applications.
Any third party applications or data made available through the Gokivo API or Gokivo Applications are subject to the third party licensing agreements accompanying those applications and data. You shall abide by and comply with all such third party agreements. TeleCommunication Systems is not a party to the agreements between you and any such third party and disclaims all warranties of any kind, statutory or otherwise, for any third party application or data. You waive all claims and release TeleCommunication Systems of all liability in connection with your use of any third party applications or data.
5. NO Warranty.
6. Limitation of Liability.
TO THE MAXIMUM EXTENT ALLOWED BY LAW, IN NO EVENT SHALL TELECOMMUNICATION SYSTEMS, ITS AFFILIATES, THIRD PARTY PROVIDERS, OR DISTRIBUTORS BE LIABLE, WHETHER IN CONTRACT, TORT (INCLUDING NEGLIGENCE), PRODUCT LIABILITY OR ANY OTHER FORM OF LIABILITY, FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THE DISTRIBUTION, USE OR INABILITY TO USE THE GOKIVO API AND/OR THE GOKIVO APPLICATIONS EVEN IF TELECOMMUNICATION SYSTEMS, ITS AFFILIATES, THIRD PARTY PROVIDERS, OR DISTRIBUTORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
You shall indemnify, defend and hold TeleCommunication Systems, its officers, directors, agents, affiliates, licensors and their suppliers (the "Indemnified Parties") harmless from and against any claim or liability arising out of:
(a) your use of the Gokivo API;
(b) the User Application;
8. Term and Termination.
9. Export Compliance.
You are responsible for applying for and obtaining all export and import licenses and/or authorizations related to the Integrated Application, including without limitation all such licenses and authorizations required by the U.S. Department of Commerce.
10. U.S. Government End Users.
11. Independent Parties.
12. Governing Law; Venue.
13. Waivers and Amendments.
16. Entire Agreement.