Gokivo® Application to Application API
An application programming interface (API) can be called by applications running on an Apple® iPhone to invoke Gokivo to provide navigation services. iPhone applications use the API to pass location information to Gokivo in the form of a URL query. Gokivo services use information from the query to create a navigation route to a destination.

Application Discovery

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
Gokivo gokivonavigator :app2app

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

Examples:

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>

Examples:

version=1.0&commands=N&street=1234%Elm%20St&city=Pleasantville&state=CA

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];

Errors

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:

  • Invalid URL format
  • Invalid location coordinates
  • Invalid combinations of query parameters

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.

Field Name Description
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:
  • fastest
  • shortest
  • easiest
If not specified in the URL query, navroutetype defaults to the navigation route type currently assigned in Gokivo Settings.
navavoid Road features to avoid while routing. Which can be one or more of the following:
  • "C" = HOV/Car pool lanes
  • "H" = Highways
  • "T" = Toll Roads
  • "F" = Ferries
If navavoid is not specified in the URL query, route avoidance features default to the current avoidance features specified in Gokivo Settings.

Use empty string to specify no avoids.
navvehicletype Navigation mode to use for a trip, which can be one of the following:
  • car
  • truck
  • bicycle
If not specified in the URL query, navvehicletype defaults to the current navigation mode specified in Gokivo Settings.
navshow Type of optional content to display during navigation. One or more of:
  • "S" = Realistic Signs
  • "J" = 3D Junctions
  • "C" = 3D Cities
  • "P" = Places on Map
navtraffic Specifies the way traffic will be used to generate the route. One and only one of:
  • "A" = Alerts only – traffic shall not be used to generate route, but traffic updates will be displayed during the route.
  • "N" = Navigation – traffic shall be used to generate the best route and traffic updates will be displayed during the route.
  • "D" = Disabled – traffic shall not be used to generate route and no traffic updates for the route.

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

gokivonavigator:app2app?version=1.0&credential=123&commands=N&name=Marriott%20John%20Wayne%20Airport&street=18000%20Von%20Karman%20Ave&city=Irvine&state=CA&postal=92612&country=USA&lat=33.67972&lon=-117.85092&navavoid=C&navroutetype=fastest&navvehicletype=car

Navigate to Coordinates: 33.67972, -117.85092

gokivonavigator:app2app?version=1.0&commands=N&lat=33.67972&lon=-117.85092

Navigate to an Address: 6 Liberty, Aliso Viejo, 92656 USA (Avoid Toll Roads)

gokivonavigator:app2app?version=1.0&commands=N&street=6%20Liberty&city=Aliso%20Viejo&state=CA&postal=92656&country=USA&lat=33.559712&lon=-117.728649&navavoid=T

Navigate to an Intersection: Del Mar Heights Rd and Carmel Canyon Rd, San Diego, CA 92130 (Avoid Highways)

gokivonavigator:app2app?version=1.0&commands=N&street=Del%20Mar%20Heights%20Rd&xstreet=Carmel%20Canyon%20Rd.&city=San%20Diego&state=CA&postal=92130&lat=32.946776&lon=-117.219182&navavoid=H

Navigate to a Place in a Plaza: Jamba Juice at Del Mar Highlands Town Center

gokivonavigator:app2app?version=1.0&commands=N&name=Jamba%20Juice&locname=Del%20Mar%20Highlands%20Town%20Center&street=3545%20Del%20Mar%20Heights%20Rd&city=San%20Diego&state=CA&postal=92130&lat=32.954137&lon=-117.230443

Navigate to an Airport: LAX Airport (Easiest Route)

gokivonavigator:app2app?version=1.0&commands=N&name=Los%20Angeles%20International%20Airport&lat=33.94406556&lon=-118.408294&navroutetype=easiest

Navigate to a City: San Francisco (Truck)

gokivonavigator:app2app?version=1.0&commands=N&city=San%20Francisco&state=CA&country=USA&lat=37.775196&lon=-122.419204&navvehicletype=truck

Navigate to a Zip Code: 92656 (Car)

gokivonavigator:app2app?version=1.0&commands=N&postal=92656&lat=37.775196&lon=-122.419204&navvehicletype=car

BY USING THE GOKIVO API, YOU AGREE TO THE TERMS OF USE.

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.

The Gokivo API (including the technical information provided below) are subject to the following Terms of Use (it is a legal agreement). By using the Gokivo API you (and any company you represent) agree to these Terms of Use and our Privacy Policy http://gokivo.com/privacy.html.  IF YOU DO NOT AGREE WITH THE TERMS OF USE AND OUR PRIVACY POLICY, DO NOT USE THE GOKIVO API. If you have any questions regarding the Gokivo API, the Terms of Use or our Privacy Policy, please contact us at contactus@gokivo.com.

GOKIVO API TERMS OF USE

1. Definitions.

  • 1.1

    "User Application" shall mean the application(s) that you use with the Gokivo API.

  • 1.2

    "Integrated Application" shall mean the User Application as modified by the Gokivo API.

  • 1.3

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

  • 2.1

    License Grants. Subject to these Terms of Use, TeleCommunication Systems grants you the following limited, non-exclusive, worldwide, royalty-free licenses:

    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.

  • 2.2

    Restrictions. Except to the extent permitted under these Terms of Use or by applicable law, you shall not: (i) allow third parties to access or use the Gokivo API or otherwise disclose it to third parties; (ii) modify, reverse assemble, reverse compile or reverse engineer any portion of the Gokivo API or the Gokivo Applications; (iii) lease, rent, copy, distribute or sublicense the Gokivo API; or (iv) remove, efface or obscure any copyright notices, logos or other proprietary notices or legends included in the Gokivo API.

  • 2.3

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

  • 2.4

    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.

3. Ownership.

  • 3.1

    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.

  • 3.2

    Integrated Application. Subject to TeleCommunication Systems's ownership of the Gokivo API, the licenses granted to you in these Terms of Use, TeleCommunication Systems agrees that relative to TeleCommunication Systems, you are and shall remain the owner of all right, title and interest in and to the Integrated Application, including all associated patents, copyrights, trademarks and other intellectual property rights therein. TeleCommunication Systems further agrees that relative to TeleCommunication Systems, you are and shall remain the owner of all right, title and interest in and to the User Application, including all associated patents, copyrights, trademarks and other intellectual property rights therein.

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.

THE GOKIVO API AND THE GOKIVO APPLICATIONS ARE AVAILABLE AS-IS WITHOUT WARRANTY OF ANY KIND. TO THE FULLEST EXTENT PERMITTED BY LAW, TELECOMMUNICATION SYSTEMS DISCLAIMS ALL EXPRESS, IMPLIED, AND STATUTORY WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED BY YOU FROM TELECOMMUNICATION SYSTEMS, OR THROUGH OR FROM OUR WEBSITE, PRODUCTS OR SERVICES, WILL CREATE ANY WARRANTY NOT EXPRESSLY STATED IN THESE TERMS OF USE.

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.

7. Indemnification.

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;

(c) your Integrated Application; including but not limited to claims related to a breach of the Terms of Use, breach of third party agreements related to the use of the Gokivo Application, violations of any applicable law or published industry standards, infringement of a third party's rights. TeleCommunication Systems reserves the right to assume the exclusive defense and control of any claim if you do not, in TeleCommunication Systems's sole opinion, take prompt action to defend and indemnify the Indemnified Parties with reasonably adequate counsel.

8. Term and Termination.

These Terms of Use shall continue until terminated by either you or TeleCommunication Systems as set out below. At any time, you may terminate your legal agreement with TeleCommunication Systems by discontinuing your use of the Gokivo API. You do need to provide us notice of your termination. At any time, TeleCommunication Systems may terminate its legal agreement with you or cease providing all or any part of the Gokivo API immediately without any notice or by posting a notice of discontinuance on gokivo.com or any TeleCommunication Systems, affiliate or successor website. Upon termination, you shall stop distribution of the Integrated Application and update, as soon as reasonably possible, the Integrated Application so that it no longer contains the Gokivo API. The Sections entitled Restrictions, Remedies, Ownership, No Warranty, Limitation of Liability, Indemnification, Term and Termination, and Governing Law; Venue shall survive the termination of these Terms of Use for any reason.

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.

Any software covered under these Terms of Use, are a "commercial item" as that term is defined at 48 C.F.R. 2.101, consisting of "commercial computer software" and "commercial computer software documentation" as such terms are used in 48 C.F.R. 12.212. Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4, all U.S. Government end users acquire any software and documentation covered under these Terms of Use with only those rights set forth therein.

11. Independent Parties.

By entering into these Terms of Use or using the Gokivo API, each of the parties is acting as an independent contractor. Neither party shall have any right, power or authority to create, and shall not represent to any person that it has the power to create any obligation, express or implied, on the other's behalf without the express prior written consent of such party.

12. Governing Law; Venue.

These Terms of Use are deemed entered into in California and shall be governed and construed in all respects by the laws of the State of California, without giving effect to principles of conflict of law. Any litigation or other dispute resolution between the parties relating to these Terms of Use shall take place only in Orange County, California. The parties consent to the personal jurisdiction of, and venue in, the state and federal courts within that county and hereby waive any objection to such jurisdiction and venue on any grounds, including the convenience of the forum.

13. Waivers and Amendments.

All waivers must be in writing. Any waiver or failure to enforce any provision of these Terms of Use on one occasion will not be deemed a waiver of any other provision or of such provision on any other occasion. These Terms of Use may be amended by TeleCommunication Systems from time to time without advance notice by posting the new Terms of Use on gokivo.com or any successor website.

14. Assignment.

These Terms of Use may be assigned by TeleCommunication Systems and will inure to the benefit of TeleCommunication Systems, its successors and assigns.

15. Severability.

If any provision of these Terms of Use (or any portion thereof) is invalid, illegal or unenforceable, the validity, legality and enforceability of the remainder of these Terms of Use shall not be affected or impaired.

16. Entire Agreement.

These Terms of Use and the Privacy Policy contain the entire agreement between us with respect to its subject matter and supersedes all existing agreements and all other oral, written or other communications between the parties concerning this subject matter.