Documentation

Places Sunset

Algolia Places is being sunset on May 31st, 2022. We invite you to read our announcement and consider alternatives.

Important: Sign-ups have been disabled.

What is Places?

Algolia Places is a geocoder providing a fast, distributed and easy way to use an address search autocomplete on your website. It is available as a Javascript autocomplete library, as a REST API and inside the JS, PHP, Swift and Android Algolia API clients.

Important: Algolia Places relies on OpenStreetMap data. Due to the sparseness of house level data in OSM, Places supports geocoding only up to the street level - house level precision is not guaranteed.

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.19.0"></script>

Here's a small example using it:

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

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

Note: You can access your Places credentials from the dashboard like any other Algolia application.

Important: We recommend using jsDelivr only for prototyping, not for production applications. Whenever possible, you should host your assets yourself or use a premium CDN service. jsDelivr is a free service and isn’t operated by Algolia, so we won’t be able to provide support if it fails.

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
5
6
var places = require('places.js');
var placesAutocomplete = places({
  appId: 'YOUR_PLACES_APP_ID',
  apiKey: 'YOUR_PLACES_API_KEY',
  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
6
7
const options = {
  appId: 'YOUR_PLACES_APP_ID',
  apiKey: 'YOUR_PLACES_API_KEY',
  container: '#my-input-DOM-selector',
  // ...
};
places(options);

Advanced example using all parameters:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const fixedOptions = {
  appId: 'YOUR_PLACES_APP_ID',
  apiKey: 'YOUR_PLACES_API_KEY',
  container: document.querySelector('#demo'),
};

const reconfigurableOptions = {
  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
};
const placesInstance = places(fixedOptions).configure(reconfigurableOptions);

// dynamically reconfigure options
placesInstance.configure({
  countries: ['us'] // only search in the United States, the rest of the settings are unchanged: we're still searching for cities in German.
})

Tip: Places application IDs always start by pl, which makes them recognizable at a glance.

Options

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

Static options

These options can only be set during the instantiation of the places application using

1
const placesInstance = places(options)

1
2
3
4
5
6
7
8
9
accessibility: {
  pinButton: {
    'aria-label': 'use browser geolocation',
    'tab-index': 12,
  },
  clearButton: {
    'tab-index': 13,
  }
}

Reconfigurable options

These options can be set during the instantiation of the places application using

1
const placesInstance = places(options)

or at any time using

1
placesInstance.configure(options)

Advanced static options

These are very advanced options that can be only set during the instantiation of the places application using

1
const placesInstance = places(options)

These options should not be considered for regular use cases.

Events

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

1
2
3
4
5
6
7
var placesAutocomplete = places({
  appId: 'YOUR_PLACES_APP_ID',
  apiKey: 'YOUR_PLACES_API_KEY',
  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'
// }

Integrations

On top of the regular places component, the places.js library offers additional integrations with autocomplete.js and InstantSearch.js.

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.19.0/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.

Important: With the release of InstantSearch.JS v4, the places widget has been re-worked and is now living in the InstantSearch repository. You can find an example of how to setup the widget in the geo-search story of the InstantSearch repository

If you are using InstantSearch v3, you can rely on the example below.

You can include it using a link tag:

1
<script src="https://cdn.jsdelivr.net/npm/places.js@1.19.0/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:

Security

The default way of using Places is to pass your Places application ID and API Key to the Places library.
However, since the Places library is user-facing, this means that your credentials can be exposed.

It is therefore recommended to put in place some extra limitations in order to prevent any abuse of your API Key. Algolia offers two solutions to restrict the usage of your API Keys, which can be combined together:

• restricted API Keys
• secured API Keys

Note: This section will not go in extreme details about the concepts that are presented as they are explained in great lengths in the official Algolia documentation.

Restricted API Keys

In Places like in any other Algolia application, you can set up authorizations and restrictions with a great level of precision when creating API keys. It’s common to combine these rules to make it very hard to use a public API key to crawl your data.

You can read more about creating restricted API Keys in the official Algolia documentation.

For instance, for Places, it is common practice to have a restricted API Key with the following restrictions:

• Rate limiting per IP
• Restricting the HTTP Referer to your website (Read about the limitations)

Designing such an API Key will protect your API Key from being used by other website, while partially mitigating attacks from other tools without having to implement an advanced security system or having to route your calls through your backend for validation, which would increase the latency of each query.

Secured API Keys

If you want to have strong control on who accesses Places with your API Key, you can use secured API Keys. This will require a back-end implementation of the secured API Key generation.

For instance, for Places, you can create short-lived API Keys for every single user based on your own metrics, using secured API Keys.

There is a great tutorial on how to use secured API Keys in the official documentation of Algolia.

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.

Licenses & Policies

You can display Algolia Places results on any map provider.

In accordance with our terms of use, you are required to comply with our Acceptable Use Policy.

If your application uses places.js library, then the Algolia logo must be included and must not be altered (size, colors, position, linked URL, etc.). If your application uses the Places API directly or any other API client, you must show a "Search by Algolia" logo next to the data. You can find the logo in SVG format here.

The places.js is licensed under MIT.

Address data is produced regularly processing different datasets such as:

© OpenStreetMap using the Planet.osm dataset under the Open Database License (ODbL) v1.0.

© GeoNames database under the Creative Commons Attribution 4.0 License.

BAN dataset for France under ODbL v1.0.

IGN Admin Express dataset under the Open License 1.0.

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.

Examples

Have a look at our examples page.