WrldSearchbar

The WrldSearchbar is an optional widget for searching on the map. Users can search for Places (points of interest), as well as geographical locations. The searchbar can also optionally have a menu with preset options for various searches.

To configure the Places that are available to search for on a map, use the Places Designer.

Dependencies

JQuery
wrld.css
searchbar.js

For an example of how to add a WrldSearchbar to a map, see this example.

Constructor

var searchbarConfig = {
    apiKey: "your_api_key_here"
};
var searchbar = new WrldSearchbar("widget-container", map, searchbarConfig);

Argument	Type	Description
id	string	The id of the DOM element to contain the searchbar.
map	`Wrld.map`	The map object that the searchbar controls.
options	object	An object containing optional parameters, described below.

Options

Options	Type	Default	Description
apiKey	string	null	A valid API key which is required by the default `placesSearchService`.
geoNamesUsername	string	null	A valid GeoNames username, required by the default `locationSearchService`.
skipYelpSearch	boolean	false	Whether to ignore Yelp results when searching. By default, Yelp search results are included.
outdoorSearchMenuItems	[SearchTag]	[]	“Find” options to display in the search menu when outdoors.
indoorSearchMenuItems	[SearchTag]	[]	“Find” options to display in the search menu when indoors.
overrideIndoorSearchMenuItems	boolean	false	Whether to override the “Find” options specific to the indoor map.
locationJumps	[LocationJump]	[]	“Location” options to display in the search menu.
placesSearchService	PlacesSearchService	*	The service to use when searching for Places, points of interest. The default searches for any Places associated with the given API key. To configure these, use the Places Designer.
locationSearchService	LocationSearchService	*	The service to use when searching for geographical locations, like city names. The default uses GeoNames.

Methods

searchbar.openMenu()

Opens the searchbar menu. The menu is only available if either the "outdoorSearchMenuItems" or "locationJumps" options were specified at construction.

searchbar.closeMenu()

Closes the searchbar menu. The menu is only available if either the "outdoorSearchMenuItems" or "locationJumps" options were specified at construction.

searchbar.clear()

Clears any search results.

Events

The following events can be listened to :

Event	Data	Description
inputchange	InputChangeEvent	Fired when the user inputs into the searchbar.
search	Event	Fired when the user performs a search.
searchresultsupdate	SearchResultsUpdateEvent	Fired when new search results appear.
searchresultselect	SearchResultSelectEvent	Fired when a search result is clicked.
searchresultsclear	Event	Fired when the search results are cleared.
menuopen	Event	Fired when the menu is opened.
menuclose	Event	Fired when the menu is closed.
autocompleteoptionselect	AutocompleteOptionSelectEvent	Fired when the user clicks an autocomplete option.

InputChangeEvent

Property	Type	Description
input	string	The text that the user has input so far.

SearchResultsUpdateEvent

Property	Type	Description
results	{ number: SearchResult }	Data for all Places matching the performed search. Each key in this object is a unique ID for the corresponding `SearchResult` value.

SearchResultSelectEvent

Property	Type	Description
result	SearchResult	Data for the Place selected by the user.

AutocompleteOptionSelectEvent

Property	Type	Description
option	AutocompleteOption	Data for the autocomplete option selected by the user.

PlacesSearchService

In order to override the default place searching, an object which implements this interface can be passed to the WrldSearchbar constructor as the "placesSearchService" option.

Any object which has the following methods can be used.

Methods

fetchAllNearbyPlaces(latLng, callback)

This method should search for nearby Places, and return them by passing them to the given callback.

Argument	Type	Description
latLng	Wrld.LatLng	The center of the map.
callback	function	A function to be called when the search is complete. The function should take an array of `SearchResult` objects as its only argument.

fetchNearbyPlacesByTerm(latLng, term, callback)

This method should search for nearby Places which match the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	Wrld.LatLng	The center of the map.
term	string	A plain text search term.
callback	function	A function to be called when the search is complete. The function should take an array of `SearchResult` objects as its only argument.

fetchNearbyPlacesByTag(latLng, tag, callback)

This method should search for nearby Places by tag. This is useful if a search service accepts some notion of tag or category. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	Wrld.LatLng	The center of the map.
tag	string	A tag or category to search with, where a search service has a pre-determined set of such tags.
callback	function	A function to be called when the search is complete. The function should take an array of `SearchResult` objects as its only argument.

fetchAutocompleteOptions(latLng, term, callback)

This method should return Places autocomplete options for the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	Wrld.LatLng	The center of the map.
term	string	A plain text search term.
callback	function	A function to be called when the autocomplete search is complete. The function should take an array of `AutocompleteOption` objects as its only argument.

fetchTagOptions(term, callback)

This method should return tag autocomplete options. This is useful if a search service accepts some notion of tag or category. The results should be returned by passing them to the given callback.

Argument	Type	Description
term	string	A plain text search term.
callback	function	A function to be called when the tag autocomplete search is complete. The function should take an array of `SearchTag` objects as its only argument.

LocationSearchService

In order to override the default location searching, an object which implements this interface can be passed to the WrldSearchbar constructor as the "locationSearchService" option.

Any object which has the following methods can be used.

Methods

fetchNearbyLocationsByTerm(latLng, term, callback)

This method should search for nearby locations which match the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	Wrld.LatLng	The center of the map.
term	string	A plain text search term.
callback	function	A function to be called when the search is complete. The function should take an array of `LocationSearchResult` objects as its only argument.

fetchAutocompleteOptions(latLng, term, callback)

This method should return location autocomplete options for the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	Wrld.LatLng	The center of the map.
term	string	A plain text search term.
callback	function	A function to be called when the autocomplete search is complete. The function should take an array of `LocationSearchResult` objects as its only argument.

Data Types

There are a few data types used by the search bar and its associated events and services. This section describes the structure of these objects, and the types of their fields.

SearchTag

Below is the structure of a SearchTag object which represents the label and icon to display, and the tag to search for. Valid iconKey values can be found here.

{
    "name": string,
    "iconKey": string,
    "searchTag": string
}

LocationJump

Below is the structure of a LocationJump object which represents the label to display in the menu, and a Wrld.LatLng to jump to when clicked. Fields with a ? following them are optional and may be omitted.

{
    "name": string,
    "latLng": Wrld.LatLng,

    "zoom": number?,
    "headingDegrees": number?
}

SearchResult

Below is the structure of a SearchResult object. Fields with a ? following them are optional and may be omitted.

For more details about this format, see the POI API documentation.

{
    "title": string,
    "location": {
        "latLng": Wrld.LatLng,

        "elevation": number?,
        "isIndoor": boolean?,
        "indoorId": string?,
        "floorIndex": number?
    },
    "sourceId": any,

    "data": object?,
    "source": string?,
    "subtitle": string?,
    "iconKey": string?,
    "tags": [string]?
}

LocationSearchResult

Below is the structure of a LocationSearchResult object. Fields with a ? following them are optional and may be omitted.

{
    "title": string,
    "location": {
        "latLng": Wrld.LatLng,

        "zoom": number?,
        "headingDegrees": number?
    }

    "subtitle": string?,
    "iconKey": string?
}

AutocompleteOption

Below is the structure of an AutocompleteOption object. Fields with a ? following them are optional and may be omitted.

{
    "title": string,
    "location": {
        "latLng": Wrld.LatLng,

        "isIndoor": boolean?,
        "indoorId": string?,
        "floorIndex": number?
    }

    "subtitle": string?,
    "iconKey": string?
}