PHPackages                             swixpop/locate - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. swixpop/locate

ActiveCraft-plugin[Search & Filtering](/categories/search)

swixpop/locate
==============

Harness the power of the Google Autocomplete API inside Craft. Adds an autocomplete search box to Craft entries.

2.1.1(7y ago)154.8k6[5 issues](https://github.com/swixpop/craft-locate/issues)[2 PRs](https://github.com/swixpop/craft-locate/pulls)MITPHPPHP ^7.0CI failing

Since Apr 24Pushed 4y ago2 watchersCompare

[ Source](https://github.com/swixpop/craft-locate)[ Packagist](https://packagist.org/packages/swixpop/locate)[ RSS](/packages/swixpop-locate/feed)WikiDiscussions craft3 Synced 2w ago

READMEChangelog (5)Dependencies (1)Versions (6)Used By (0)

Locate plugin for Craft CMS 3.x
===============================

[](#locate-plugin-for-craft-cms-3x)

Harness the power of the [Google Autocomplete API](https://developers.google.com/maps/documentation/javascript/places-autocomplete) inside Craft. Adds an autocomplete search box to Craft entries which allows place and address queries to be made to the API. Populates a hidden **Location** field with `lat`, `lng`, `location`, and `placeid` which you can grab in your templates to do with as you wish.

Requirements
------------

[](#requirements)

- [Craft CMS](https://craftcms.com/) 3.0.0-beta.23 or later.
- [Google API key](https://developers.google.com/maps/documentation/javascript/get-api-key) with ` Google Maps JavaScript API` and `Google Places API Web Service` enabled.

#### Note:

[](#note)

Google has updated their API access policy. See

Installation
------------

[](#installation)

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

    ```
     cd /path/to/project

    ```
2. Then tell Composer to load the plugin:

    ```
     composer require swixpop/locate

    ```
3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Locate, or from the command line:

    ```
     ./craft install/plugin locate

    ```
4. Configure the plugin via the plugin settings page in the control panel.
5. You can now create `Location` fields and add them to your entries.

Configuration
-------------

[](#configuration)

Navigate to Settings > Plugins > Locate. Enter your Google API key if you already have one, or [get one here](https://developers.google.com/maps/documentation/javascript/get-api-key). The settings page also allows you to customize the behaviour of the autocomplete box.

### Customize the autocomplete box

[](#customize-the-autocomplete-box)

The autocomplete search box need not be customized. It defaults to all place types (cities, addresses, businesses, etc.) in the world. By default, the API will attempt to detect the user's location from their IP address, and will bias the results to that location.

However, by passing in some basic options, advanced filtering can be achieved. You can modify the default behaviour by passing in a JSON object of options. For a full list of allowed options see the [official documentation from Google](https://developers.google.com/maps/documentation/javascript/places-autocomplete#add_autocomplete).

These options can be set globally or on a per field basis. Options set on individual fields will override the global options.

**The options object must be formatted correctly or the plugin will throw a javascript error! If after reading this documentation you are unclear about what to enter in the options box, please leave it blank.**

#### Restrict search by place type

[](#restrict-search-by-place-type)

You can specify an array of `types` to restrict the results returned to your autocomplete box. In general only a single type is allowed. Possible values are:

- `geocode`
- `address`
- `establishment`
- `(regions)`
- `(cities)`

See the [official documentation](https://developers.google.com/maps/documentation/javascript/places-autocomplete#add_autocomplete) for details on how using these `types` will restrict your results.

##### Example usage

[](#example-usage)

Restrict the results to cities:

```
"types": ["(cities)"]
```

Restrict the results to business establishments:

```
"types": ["establishment"]
```

#### Bias the search towards a geographical already

[](#bias-the-search-towards-a-geographical-already)

You can use the `bounds` property to specify a `google.maps.LatLngBoundsLiteral` and bias your search results to a geographic area. This is an object specifying `north`, `east`, `south`, and `west` values. The autocomplete box return results biased towards, *but not restricted to*, the area you specify.

See the [LatLngBoundsLiteral object specification](https://developers.google.com/maps/documentation/javascript/reference#LatLngBoundsLiteral) for full details.

Note that the values are entered as a *number* and not a *string*

##### Example usage

[](#example-usage-1)

Bias the search results to the Pacific Northwest:

```
"bounds": {
  "north": 50,
  "east": -122,
  "south": 48,
  "west": -123
}
```

#### Restrict search by country

[](#restrict-search-by-country)

You can restrict results to an individual country using the `componentRestrictions` property. The country must be passed as as a two-character, ISO 3166-1 Alpha-2 compatible country code.

##### Example usage

[](#example-usage-2)

Restrict the results to Canada:

```
"componentRestrictions": {
  "country": "ca"
}
```

#### Putting it all together

[](#putting-it-all-together)

Using the above examples we can create an options object that restricts searches to businesses in Canada, preferably in the Pacific Northwest region (ie. Starbucks in Vancouver).

```
"types": ["establishment"],
"bounds": {
  "north": 50,
  "east": -122,
  "south": 48,
  "west": -123
},
"componentRestrictions": {
  "country": "ca"
}
```

Using the Location field
------------------------

[](#using-the-location-field)

The Location field returns `locationData`, `lat`, `lng`, `location`, and `placeid`. You can use these in your templates and pass them on to your javascript.

- `locationData` returns the full API response from Google, with an additional `components` array which maps the `address_components` to an an array with the component types as keys. See [here](https://developers.google.com/maps/documentation/geocoding/intro#Types) for a list of some types. (For example, you can access `locationData.components.country` in your twig. You can also add `_short` to any component key to access the `short_name` of that address component, for example `locationData.components.country_short`).
- `lat` returns the latitude of the place
- `lng` returns the longitude of the place
- `location` returns autocomplete query
- `placeid` returns a textual identifier that uniquely identifies a place

The `placeid` can be used to make additional requests to the Google Maps API. With `placeid` you can make [place details requests](https://developers.google.com/maps/documentation/javascript/places#place_details_requests) to get information such as address, phone number, reviews, etc. You can also use the `placeid` to generate map markers. Read more about [referencing a place with a place ID](https://developers.google.com/maps/documentation/javascript/places#placeid).

### Templating examples

[](#templating-examples)

Using the options restrictions from the previous section, we could search for "Lucky's Donuts" in the autocomplete box.

```

  You searched for: {{ entry.myLocationFieldHandle.location }}

```

would generate the following:

```

  You searched for: Lucky's Doughnuts, Main Street, Vancouver, BC, Canada

```

You could then generate a simple map by loading up the Google Maps javascript API:

```

```

and grabbing the `placeid`, `lat`, and `lng` in your javascript:

```
var map,
    myLat = $('.yummy').attr('data-lat'),
    myLng = $('.yummy').attr('data-lng'),
    myPlaceId = $('.yummy').attr('data-place-id');

function initialize() {
  // Create a map centered at your location.
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: myLat, lng: myLng},
    zoom: 15
  });

  var myLatLng = new google.maps.LatLng({lat: myLat, lng: myLng});

  var marker = new google.maps.Marker({
    map: map,
    place: {
      placeId: myPlaceId,
      location: myLatLng
    }
  });
}

google.maps.event.addDomListener(window, 'load', initialize);
```

Brought to you by [Isaac Gray](https://www.vaersaagod.no/)

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance13

Infrequent updates — may be unmaintained

Popularity27

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~77 days

Total

5

Last Release

2679d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7113101?v=4)[Isaac Gray](/maintainers/swixpop)[@swixpop](https://github.com/swixpop)

---

Top Contributors

[![swixpop](https://avatars.githubusercontent.com/u/7113101?v=4)](https://github.com/swixpop "swixpop (12 commits)")

---

Tags

addressmapcmsCraftcraftcmscraft-plugingoogle mapslocatelocationsproximity-search

### Embed Badge

![Health badge](/badges/swixpop-locate/health.svg)

```
[![Health](https://phpackages.com/badges/swixpop-locate/health.svg)](https://phpackages.com/packages/swixpop-locate)
```

###  Alternatives

[doublesecretagency/craft-googlemaps

Maps in minutes. Powered by the Google Maps API.

1269.5k](/packages/doublesecretagency-craft-googlemaps)[verbb/formie

The most user-friendly forms plugin for Craft.

100387.6k58](/packages/verbb-formie)[studioespresso/craft-scout

Craft Scout provides a simple solution for adding full-text search to your entries. Scout will automatically keep your search indexes in sync with your entries.

80141.4k](/packages/studioespresso-craft-scout)[verbb/hyper

A user-friendly links field for Craft.

24142.6k12](/packages/verbb-hyper)[verbb/social-poster

Automatically post entries to social media.

918.5k](/packages/verbb-social-poster)[la-haute-societe/craft-elasticsearch

Bring the power of Elasticsearch to your Craft CMS projects.

1712.4k](/packages/la-haute-societe-craft-elasticsearch)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)