Algolia Places is closing. We can help.

Front-End Usage

Introduction #

PlacesAPI works like a pre-populated Algolia account of your own so you can get started very quickly. For front-end implementations you simply need to install the Autocomplete library (see below) and connect to our Algolia App and index with your own API key.

So the first step is to create a new API key in your dashboard.

Algolia Info #

To begin searching you'll need our Algolia app details:

Item Value

Algolia App ID

DM340JGS49

Algolia Index

places

Install Algolia Autocomplete #

If you don’t want to use a package manager you can use a standalone script from a CDN:

# CSS

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-theme-classic"/>

# JS

<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-js"></script>

<script>
    const { autocomplete } = window['@algolia/autocomplete-js'];
</script>
        

Otherwise, Autocomplete is available via yarn or npm.

yarn add @algolia/autocomplete-js
yarn add @algolia/autocomplete-theme-classic

# or

npm install @algolia/autocomplete-js
npm install @algolia/autocomplete-theme-classic
        

View our codepen demos and the official Algolia Autocomplete documentation to learn how to configure Autocomplete to suit your needs, it is extremely flexible.

Filters #

If you don't want to search our entire data set you can use filters to search a subset of the index. This is useful if you want to limit results to a specific country, county etc.

Note the params object being passed to getAlgoliaResults below:

autocomplete({
    container: "#search-container",
    detachedMediaQuery: "none",
    placeholder: "Search for places...",
    getSources() {
        return [{
            sourceId: "places",
            getItems({ query }) {
                return getAlgoliaResults({
                    searchClient,
                    queries: [
                        {
                            indexName: "places",
                            query,
                            params: {
                                filters: 'country:"England" OR country:"Wales"'
                            }
                            
                        },
                    ],
                });
            },
            templates: {
                item({ item }) {
                    return `${item.name}, ${item.county}, ${item.country}`;
                },
            },
            onSelect: function (event) {
                event.setQuery(
                    event.item.name + ", " + event.item.county + ", " + event.item.country
                );
            },
        }];
    },
});
        

A NOT filter, for example to exclude a country code, can be added using:

return getAlgoliaResults({
    ...
    queries: [
        {
            ...
            params: {
                filters: 'NOT country_code:"ie"'
            }
            
        },
    ],
});
        

The following fields can have filters applied:

Field Filter Type

type

string

county

string

country

string

country_code

string

region

string

irish_province

string

gov_area

string

You can mix and match filters using AND, OR and NOT clauses. For string filters we recommend wrapping the filter string in quotes (as per the example above) otherwise strings with spaces will not match.

See the Algolia docs for full details and further examples.

Geo search #

You can help your users by ranking results around a single lat/long point, either by providing a lat/long coordinate when searching or automatically via the user's IP address. This improves the user experience when searching for nearby places.

You can also limit the search radius in metres using the aroundRadius option.

The aroundLatLng option:

autocomplete({
    ...
        return getAlgoliaResults({
            ...
            queries: [
                {
                    indexName: "places",
                    query,
                    params: {
                        aroundLatLng: '51.5287718,-0.2416818'
                    }
                    
                },
            ],
        });
    ...
});
        

The aroundLatLngViaIP option:

autocomplete({
    ...
        return getAlgoliaResults({
            ...
            queries: [
                {
                    indexName: "places",
                    query,
                    params: {
                        aroundLatLngViaIP: true
                    }
                    
                },
            ],
        });
    ...
});
        

The aroundRadius option:

When using either of the options above to rank results by distance from a point, you can optionally use the aroundRadius option to limit the size of the circular search area in metres.

autocomplete({
    ...
        return getAlgoliaResults({
            ...
            queries: [
                {
                    indexName: "places",
                    query,
                    params: {
                        aroundRadius: 8046 // 5 miles
                    }
                    
                },
            ],
        });
    ...
});
        

You can read more about aroundLatLng, aroundLatLngViaIP and aroundRadius in the Algolia docs.

Styling #

The autocomplete-theme-classic package is a great starting point for styling your autocomplete interface. It can be customised in a multitude of ways, see the Algolia docs for details.