Where To? API
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:
| Parameter | Example value 1) | Purpose | Availability |
|---|---|---|---|
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+ |
title |
Cafe Sunrise |
Name of the location. Requires the location parameter to be set. | 7.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:
|
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+ |
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 (
) 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"];
}