Launching Where To? from third party apps

Where To? can be launched from other apps by making use of custom URL schemes. For example, this code snippet launches Where To? and lists all nearby Bars:

NSURL *whereToUrl = [NSURL URLWithString:@"whereto://?search=Bars"];
[[UIApplication sharedApplication] openURL:whereToUrl];

To return to the calling app, Where To? 7 or higher supports the x-callback-url specification.

The URL scheme is whereto, whereto5 to require Where To? 5.0 or higher or whereto7 to require Where To? 7.0 or higher. The following GET query parameters are supported:

ParameterExample value 1)PurposeAvailability
search
Public Transport
Sets the category or name to be searched. Equivalent to starting a manual search using the Search button within the app. Notice that Where To? automatically resolves (and translates if necessary) built-in categories for optimized search quality. For instance, the provided example value is dynamically translated to “Öffentl. Verkehrsmittel” when the user’s interface language is German. 5.0+
location
37.332331,-122.031219
Sets the location using latitude, longitude to be searched at. The example value sets the location to Apple’s HQ in Cupertino. Requires the search parameter to be set. If location is not specified, Where To? will search at the current location. 5.0+
poi
8448279591557131878
Lets Where To? display a specific place. The example value will display the Apple Store in San Francisco. Not to be combined with search and location parameters! 5.0+
showDirections
whereto
Show directions to poi (if specified) or to location. If both are specified, location is used as the starting point of the route. (Either poi or location is required for this parameter.) Possible values:
  • whereto: Builtin directions with the last-selected means of transport
  • car: Builtin car directions
  • bike: Builtin bicycle directions
  • pedestrian: Builtin pedestrian directions
  • pebble: Open the Where To? Pebble companion app
  • bmw: Send location to BMW ConnectedDrive
  • mercedes-benz: Send location to Mercedes-Benz COMAND online
  • mmi-connect: Send location to Audi MMI-connect app
  • <3rd party app name>: Launch the specified 3rd party app for directions. See the list of supported apps. Use the name as printed in the app.
7.0+
x-source
Streets
Display name of the originating app. Displayed in a blue bar on top of the navigation bar. 7.0+
x-success
streets://
Callback URL to launch the originating app. Will be opened if the user taps into the blue bar on top of the navigation bar. 7.0+
x-error
streets://?failure=1
Callback URL to launch the originating app in case of an error. For instance, if a POI specified in the URL can’t be found, this error callback URL is opened. 7.0+
1) Example values are shown here in non-encoded form. In the actual URL they have to be URL-encoded.

Finding out poi values for specific places

The easiest way to determine the poi value for a specific place is to open the place in Where To? and tap the add-to-contacts button (Add to contacts Icon) beside the address. The “New Contact” screen includes the Where To? URL including the poi parameter.

Detecting if Where To? is installed

You might want to disable linking to Where To? if the app is not installed. Or you might instead want to open its App Store page. This code will do it for you:
if ([[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"whereto:"]]) {
  // launch Where To? (see first code snippet)
} else {
  // open App Store with Where To? page
  [[UIApplication sharedApplication] openURL:[NSURL URLWithString:@"itms-apps://itunes.apple.com/app/id903955898"];
}

Promoting your Where To? enabled app

We’re glad to introduce apps making use of the Where To? API on our blog. Just let us know. Also please contact us and explain your needs if you’re missing a certain API. We’re open to expand this API for new use cases.

Providing directions for Where To? users

Where To? includes support for numerous directions apps which can be launched from within the app. Technically, this is not a Where To? API but 3rd party APIs we support. Nevertheless, if you’re providing a directions app (using any kind of transport medium: car, walking, public transport…) and are not yet listed within Where To?, please let us know.