PlaceSearch.js

Create <input> fields with search ahead address autocomplete

Getting Started

To get started, first include PlaceSearch.js and PlaceSearch.css in your HTML header.

<script src="https://api.mqcdn.com/sdk/place-search-js/v1.0.0/place-search.js"></script>
<link type="text/css" rel="stylesheet" href="https://api.mqcdn.com/sdk/place-search-js/v1.0.0/place-search.css"/>

Setup the <input> element you want to use.

<input type="search" id="place-search-input" placeholder="Start Searching..."/>

Then initialize your MapQuest key and the reference to the input field element.

placeSearch({
  key: 'KEY',
  container: document.querySelector('#place-search-input')
});

Options

In the list below are the options you can pass to the placeSearch(options) function:

  • key required

    The API Key, which is needed to make requests to MapQuest services.

  • container required

    Determines the input that will be used for the dropdown menu.

    Pass a reference to an Element. Obtained via document.querySelector for example.

  • collection

    Search Ahead organizes types of data into collections, which can be requested using this parameter.

    Franchise and category collections vary and return category (SIC) codes to be used with the Place Search API

    Available Collections

    • address
    • adminArea
    • airport
    • category
    • franchise
    • poi

    Default:['airport', 'address', 'adminArea', 'poi']

  • limit

    Determines the number of results returned from the Search Ahead API.

    Default: 5. Must lie in the range [1, 15].

  • style

    Control whether the default styles should be used.

    Default: Styles are enabled, true.

  • templates

    Change the templates used.

    Available templates:

    • header: Rendered above the results list.
    • value
    • suggestion
    • footer: Rendered below the results list.
    • empty: If no results are returned, this is rendered.

    Each template is a function that will receive a result object and must return a string.

    Value must return a plain string as it's used to fill the input.value. suggestion should return an HTML string to be displayed in the dropdown.

    Header, footer, and empty should return an HTML string.

  • autocompleteOptions

    The PlaceSearch.js library is leveraging Algolia's autocomplete.js

    autocomplete.js options to configure the underlying autocomplete.js instance.

  • useDeviceLocation

    Ask and use the device location.

    Default: false.

Methods

The PlaceSearch.js library provides a few methods to interact with:

  • open

    Opens the dropdown menu. The menu will be visible if it has content to show.

    Example

    placeSearch.open()
  • close

    Closes the dropdown menu.

    Example

    placeSearch.close()
  • getVal

    Get the current input value.

    Example

    placeSearch.getVal()
  • setVal

    Set the current input value. This will not open the menu. Call open().

    Example

    placeSearch.setVal()

Events

  • change Event

    This event is fired when a result is selected in the dropdown.

    Example

    placeSearch.on('change', (e) => {
      console.log(e);
    });
  • results Event

    This event is fired when the dropdown receives results. You will receive the array of results that are displayed.

    This event is also fired when no results are found.

    Example

    placeSearch.on('results', (e) => {
      console.log(e);
    });
  • cursorchanged Event

    This event is fired when arrows keys are used to navigate suggestions.

    Example

    placeSearch.on('cursorchanged', (e) => {
      console.log(e);
    });
  • clear Event

    This event is fired when the PlaceSearch input is cleared. This event doesn't return anything, as the value of the query is then '' and no results are displayed.

    Example

    placeSearch.on('clear', (e) => {
      console.log(e);
    });
  • error Event

    This event is fired when the request to the MapQuest Search Ahead servers fails for any reason.

    Example

    placeSearch.on('clear', (e) => {
      console.log(e);
    });

Result Object

Events will return result objects with the properties below:

Key Description
type

A string that contains information about the type of result that is returned. Possible values are: address, airport, poi, postalCode, neighborhood, city, county, state, country, category, franchise.

name

A string that contains the name of the result that is returned without additional summary information included.

city

A string that contains the enclosing city of this location, if applicable to the result returned.

state

A string that contains the enclosing state or province of this location, if applicable to the result returned.

stateCode

A string that contains the enclosing two-character state code of this location, if applicable to the result returned.

country

A string that contains the enclosing country of this location, if applicable to the result returned.

countryCode

A string that contains the enclosing ISO 3166-1 Alpha-2 country code of this location, if applicable to the result returned.

latLng

An object that contains the longitude and latitude that describes the geographic location of the result that is returned.

postalCode

A string that contains the coarsest enclosing postal code, if applicable to the result returned.

searchAheadResult

The result object returned by the Search Ahead API.

value

A string that contains a summary of the result that is returned. Depending on the type of result returned, the value could include a name, street, city, state, and postal code.

Search Ahead API

The PlaceSearch.js library is powered by our Search Ahead API in the background.

HTML structure

Here is what the wrapper and input field html structure looks like:

<span class="mq-place-search">
  <input class="mq-input" />
  <button class="mq-input-icon mq-icon-clear"><svg></svg></button>
</span>

Here is what the dropdown html structure looks like:

<span class="mq-dropdown-menu mq-with-results">
  <div>
    <span class="mq-results">
      <div class="mq-result">
        <span class="mq-result-icon"><svg></svg></span>
        <span class="mq-name"></span>
        <span class="mq-address"></span>
      </div>
      <!-- More Results-->
    </span>
  </div>
</span>

CSS classes

Below is a visual overlay of the different CSS classes in PlaceSearch.js:

Place Search CSS classes
CSS Class Description
.mq-input

This class is the one used by the main PlaceSearch input.

.mq-icon-clear

This is the class attached to the clear icon, which is visible when the input has characters, clicking it will empty the input.

.mq-dropdown-menu

This class is the one that is on the whole results wrapper.

.mq-result

The .mq-result class is the class of each dropdown result.

.mq-cursor

The .mq-cursor class is added to .mq-result when the result is hovered.

.mq-result-icon

The .mq-result-icon is the class that is used on the left icon of each result.

.mq-name

The .mq-name class is used on the name of the place.

.mq-address

The .mq-address class is used on the address of the place.

Below is blank css that can be used to customize the default styling.

.mq-place-search {}

.mq-input {}

.mq-input::-webkit-search-decoration {}

.mq-input::-webkit-search-cancel-button {}

.mq-input::-ms-clear {}

.mq-input-icon {}

.mq-input-icon svg {}

.mq-dropdown-menu {}

.mq-result {}

.mq-result .mq-name {}

.mq-result .mq-address {}

.mq-result-icon {}

.mq-result-icon svg {}

.mq-cursor {}

.mq-cursor .mq-result-icon svg {}

.mq-icon-clear {}

Disable Default Styles

When initializing PlaceSearch.js, you can disable the style/formatting of input completely. The CSS classes names with be prepended with mq-no-style instead of mq-.

placeSearch({
  key: 'KEY',
  container: document.querySelector('#place-search-input'),
  style: false
});

License

The PlaceSearch.js library is leveraging Algolia's autocomplete.js library which is licensed under MIT.

MapQuest data is licensed, see our Terms and Conditions.

Cost

Each Search Ahead API request that is made costs 1/10th of a transaction. So for every 10 requests you make, you are charged 1 transaction according to our Plans Page. The PlaceSearch.js SDK doesn't start making requests to the Search Ahead API until the second character is typed.

Examples

Check out our examples for inspiration.