Documentation

Getting started

To use Algolia Places, all you need is an <input> and some JavaScript code that will load
and use the places.js library.

CDN <script>

Our JavaScript library is available on the jsDelivr CDN.

1
<script src="https://cdn.jsdelivr.net/npm/places.js@1.4.14"></script>
 

Here's a small example using it:

1
2
3
4
5
6
7
8
<input type="search" id="address-input" placeholder="Where are we going?" />

<script src="https://cdn.jsdelivr.net/npm/places.js@1.4.14"></script>
<script>
  var placesAutocomplete = places({
    container: document.querySelector('#address-input')
  });
</script>
 

Using npm

Algolia Places is also available on npm.

Install the module:

1
npm install places.js --save
 

Put an <input> in your html page:

1
<input type="search" id="address-input" placeholder="Where are we going?" />
 

Initialize the places.js library:

1
2
3
4
var places = require('places.js');
var placesAutocomplete = places({
  container: document.querySelector('#address-input')
});
 

Demo

As a result, you will get the Algolia Places autocompletion menu:

Usage

To turn any HTML <input /> into an address search bar make sure you include the places.js library and use the following initialization code:

1
2
3
4
5
var options = {
  container: '#my-input-DOM-selector',
  // ...
};
places(options);
 

Options

Here are the options you can pass to the places(options) function:

Simple example providing only the required container parameter:

1
2
3
var placesAutocomplete = {
  container: document.querySelector('#demo')
};
 

Advanced example using all parameters:

1
2
3
4
5
6
7
var placesAutocomplete = {
  container: document.querySelector('#demo'),
  language: 'de', // Receives results in German
  countries: ['us', 'ru'], // Search in the United States of America and in the Russian Federation
  type: 'city', // Search only for cities names
  aroundLatLngViaIP: false // disable the extra search/boost around the source IP
};
 

Events

The Algolia Places autocomplete exposes some events that you can register to:

1
2
3
4
5
var placesAutocomplete = {
  container: document.querySelector('#demo')
};

placesAutocomplete.on('change', e => console.log(e.suggestion));
 

Methods

We provide some methods to help you interact with the places.js autocomplete instance.
If you have a good use case for a new method, open a new issue about it.

Suggestions

All of the events will send suggestion objects with those properties:

1
2
3
4
5
6
7
// query was `par`
console.log(suggestion.highlight);
// {
//   name: '<em>Par</em>is',
//   administrative: 'Île-de-France',
//   country: 'France'
// }
 

autocomplete.js

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

To be able to combine your own data along with showing results of Algolia Places, we provide an autocomplete.js dataset:

1
<script src="https://cdn.jsdelivr.net/npm/places.js@1.4.14/dist/cdn/placesAutocompleteDataset.min.js"></script>
 

The autocomplete.js dataset is exported as placesAutocompleteDataset in the window, also available with npm using:

1
import placesAutocompleteDataset from 'places.js/placesAutocompleteDataset';
 

All the places.js options are available and can be passed to the placesAutocompleteDataset function. The places.js CSS file is automatically loaded so that the rendering of suggestions is already the one you will expect.

You will need an Algolia account to be able to search into your own data. See the autocomplete.js dataset example.

instantsearch.js

If you're already using instantsearch.js, you can use Algolia Places out of the box. This
widget will do a search of places using Algolia Places and when an address is selected, it
will update the geolocation point of the instantsearch.js search.

You can include it using a link tag:

1
<script src="https://cdn.jsdelivr.net/npm/places.js@1.4.14/dist/cdn/placesInstantsearchWidget.min.js"></script>
 

The widget is exported as placesInstantsearchWidget in the window. It is also available with
npm using:

1
import widget from 'places.js/placesInstantsearchWidget';
 

The widget accept the same options as places.js. Because it is an instantsearch.js that
will have an impact on the instantsearch search, it contains other options:

JavaScript API Client

You can directly query the Places REST API using our JavaScript API client,
either in browsers or with Node.js.

1
2
3
4
5
6
7
8
9
// var algoliasearch = require('algoliasearch');
var places = algoliasearch.initPlaces(/*appId, apiKey*/);
places
  .search(/*{REST API Params}*/, function(err, res) {
    if (err) {
      throw err;
    }
    console.log(res);
  });
 

PHP API Client

You can directly query the Places REST API with our PHP API Client,
so that you can do backend Places searches.

Without credentials (require PHP API Client >= 1.18.0):

1
2
3
4
5
6
<?php

$places = \AlgoliaSearch\Client::initPlaces();

$result = $places->search('Paris');
var_dump($result);
 

With credentials, requires a registered Places account.

1
2
3
4
5
6
7
8
9
<?php

$appId = 'YOUR_PLACES_APP_ID';
$apiKey = 'YOUR_PLACES_API_KEY';

$places = \AlgoliaSearch\Client::initPlaces($appId, $apiKey);

$result = $places->search('Paris');
var_dump($result);
 

REST API

Behind the places.js the JavaScript library lies a complete REST API. Read the underlying REST API documentation.

Styling

Algolia Places can fit existing designs. By default only the dropdown has a default light style.

See our styling example.

HTML structure

The overall html structure looks like this:

1
2
3
4
5
<span class="algolia-places">
  <input class="ap-input" />
  <button type="button" class="ap-input-icon ap-icon-clear"><svg></svg></button>
  <button type="button" class="ap-input-icon ap-icon-pin"><svg></svg></button>
</span>
 

Then the dropdown html structure looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
<span class="ap-dropdown-menu">
  <div>
    <span class="ap-suggestions">
      <div class="ap-suggestion">
        <span class="ap-suggestion-icon"><svg></svg></span>
        <span class="ap-name"></span>
        <span class="ap-address"></span>
      </div>
      <!-- Other suggestions -->
    </span>
  </div>
</span>
 

CSS classes

Here's a visual explanation of the different CSS classes:

Here's a default empty CSS file you can copy paste to tune the default styling:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
/* Main input wrapper */
.algolia-places {}

/* The algolia-places input */
.ap-input, .ap-hint {}

/* The style of the svg icons when the input is on hover */
.ap-input:hover ~ .ap-input-icon svg,
.ap-input:focus ~ .ap-input-icon svg,
.ap-input-icon:hover svg {}

/* The dropdown style */
.ap-dropdown-menu {}

/* The suggestions style */
.ap-suggestion {}

/* The highlighted names style */
.ap-suggestion em {}

/* The addresses style */
.ap-address {}

/* The icons of each suggestions ( can be a building or a pin ) */
.ap-suggestion-icon {}

/* The style of the svg inside the .ap-suggestion-icon */
.ap-suggestion-icon svg {}

/* The icons inside the input ( can be a pin or a cross ) */
.ap-input-icon {}

/* The style of the svg inside the .ap-input-icon */
.ap-input-icon svg {}

/* .a-cursor is the class a suggestion go on hover */
.ap-cursor {}

/* The style of the svg icon, when the .ap-suggestion is on hover */
.ap-cursor .ap-suggestion-icon svg {}

/* The styles of the Algolia Places input footer */
.ap-footer {}

/* The styles of the Algolia Places input footer links */
.ap-footer a {}

/* The styles of the Algolia Places input footer svg icons */
.ap-footer a svg {}

/* The styles of the Algolia Places input footer on hover */
.ap-footer:hover {}
 

Disable default style

By default we insert some styling into your page. You can disable all the Algolia Places styling by passing the style: false option.

Once you do so, all CSS classes will be prefixed with ap-nostyle and no styling will be applied anymore.

Pin and clear icons will still be shown and working, without being styled.

Browser support

Algolia Places comes with native support for all latest stable versions of current major browsers: Chrome, Firefox, Edge, Opera and Safari. Previous versions of those modern browsers should also work. But since those are auto-updating browsers, we do not guarantee it.

Algolia Places also works natively on Internet Explorer 11 and 10.

To support Internet Explorer 9, you need to include a polyfill for Element.classList. To do so, you can use the Polyfill.io service.

Rate limits

The Algolia Places API enforces some rate limits.

If you're calling the API from your backend, the rate-limits computation is then based on the source IP.

If you are using the places.js library, you will receive a limit event on the places.js instance when you reach your current rate limit.

License

Algolia Places is licensed under MIT.

Address data © OpenStreetMap and GeoNames contributors.

Examples

Have a look at our examples page.