Introduction

A powerful geocoding field type powered by the Google Maps API.

Heads Up: The Geocoder field type is a paid addon! Please checkout our store or ask about our developer partnership for repository access.

Configuration

Below is the full configuration available with defaults values:

"example" => [
    "type"   => "anomaly.field_type.geocoder",
    "config" => [
        "zoom"          => 13,
        "height"        => 400
    ]
]
Configuration
Key Example Description

zoom

10

The input map's zoom.

height

500

The input map's height.

Addon Configuration

Google API

A Google maps and geocoding API key can be provided by the field type configuration.

You can set the key by publishing the field type and setting the value:

php artisan addon:publish anomaly.field_type.geocoder // See google.php config file.

You can also set the key by setting the GEOCODER_KEY value in your .env file.

Installation

The Geocoder field type is a paid addon and requires purchasing from the addon store OR a paid subscription.

Installing from Store Download

You can install the Templates module by downloading the addon and placing it within your site's addon directory:

/addons/{application_ref}/anomaly/*
Installing with Composer Subscription

You can install the Geocoder field type with Composer as a VCS repository if you have a subscription:

{
     "require": {
        "anomaly/geocoder-field_type": "~1.1.0"
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/anomalylabs/geocoder-field_type"
        }
    ]
}
Spatial Features

In order to enable spatial features you must register Grimzy\LaravelMysqlSpatial\SpatialServiceProvider in your config/app.php file before App service providers.

Spatial Service Provider

Usage

This section will show you how to use the field type via API and in the view layer.

Setting Values

You can set the geocoder field type value with an address:

$entry->example = "1 Infinite Loop, Cupertino, CA 95014";

You can use partial addresses too:

$entry->example = "Cupertino CA";

Basic Output

The geocoder field type returns an array of data.

$entry->example;

[
    "address"=> "1 Cupertino Loop",
    "formatted" => "Infinite Loop, Cupertino, CA 95014, USA",
    "latitude" => "37.3320403",
    "longitude" => "-122.0285677",
    "formatted_latitude" => "37.3322109",
    "formatted_longitude" => "-122.0307778"
]

Presenter Output

This section will show you how to use the decorated value provided by the \Anomaly\GeocoderFieldType\GeocoderFieldTypePresenter class.

GeocoderFieldTypePresenter::image()

The image method returns a generated image of the map area.

Returns: string
Arguments
Key Required Type Default Description

$options

false

array

none

The image options.

$formatted

true

boolean

false

Use the formatted address location instead of the potentially adjusted marker location.

Example
$decorated->example->image();
Twig
{{ decorated.example.image()|raw }}
Available Option

Below are a list of available options for the image method's options argument.

Properties
Key Required Type Default Description

scale

false

integer

1

The scale of the map.

zoom

false

integer

The configured zoom.

The zoom of the map.

format

false

string

png

The output format of the image. Valid options are jpg and png.

maptype

false

string

roadmap

The Google maptype. Valid options are roadmap, satellite, hybrid, and terrain.

width

false

integer

150

The width of the resulting image.

height

false

integer

100

The height of the resulting image.

GeocoderFieldTypePresenter::embed()

The embed method returns an embedded Google map.

Heads Up: The embedded map is 0px high by default. Be sure to use CSS to style it or set the height option as described below.
Returns: string
Arguments
Key Required Type Default Description

$options

false

array

none

The image options.

$formatted

true

boolean

false

Use the formatted address location instead of the potentially adjusted marker location.

Example
$decorated->example->embed()->height(500);
Twig
{{ decorated.example.embed().height(500)|raw }}
Available Options

Below are a list of available options for the embed method's options argument.

Options
Key Required Type Default Description

scale

false

integer

1

The scale of the map.

scrollwheel

false

boolean

true

Set to false to disable scrollwheel interaction.

zoom

false

integer

15

The output map zoom.

height

false

integer

none

The style height in pixels if any of the map div.

GeocoderFieldTypePresenter::url()

The url method returns the Google Maps URL for the address.

Returns: string
Arguments
Key Required Type Default Description

$formatted

false

boolean

false

Use the formatted address location instead of the potentially adjusted marker location.

Example
$decorated->example->url();
Twig
{{ decorated.example.url() }}

GeocoderFieldTypePresenter::link()

The link method returns an HTML link to the Google Maps URL.

Returns: string
Arguments
Key Required Type Default Description

$title

true

string

none

The link title.

$attributes

false

array

none

The array of HTML attributes of the link.

$secure

false

boolean

True if request is secure.

Force a secure URL.

$formatted

false

boolean

false

Use the formatted address location instead of the potentially adjusted marker location.

GeocoderFieldTypePresenter::position()

The position method returns an array containing the longitude and latitude values.

Returns: array
Arguments
Key Required Type Default Description

$formatted

false

boolean

false

Use the formatted address location instead of the potentially adjusted marker location.

Example
$decorated->example->position()['longitude'];
Twig
{{ decorated.example.position().longitude }}

GeocoderFieldTypePresenter::latitude()

The latitude method is a shortcut to return the value's latitude position.

Returns: float
Arguments
Key Required Type Default Description

$formatted

false

boolean

false

Use the formatted address location instead of the potentially adjusted marker location.

Example
$deocrated->example->latitude();
Twig
{{ decorated.example.latitude() }}

GeocoderFieldTypePresenter::longitude()

The longitude method is a shortcut to return the value's longitude position.

Returns: float
Arguments
Key Required Type Default Description

$formatted

false

boolean

false

Use the formatted address location instead of the potentially adjusted marker location.

Example
$decorated->example->longitude();
Twig
{{ decorated.example.longitude() }}

GeocoderFieldTypePresenter::point()

The point method returns a Point instance for use within spatial utilities.

Returns: \Anomaly\GeocoderFieldType\Spatial\Point
Arguments
Key Required Type Default Description

$formatted

false

bool

none

Whether to use the formatted latitude and longitude instead of the adjustable marker.

Example
$decorated->point();
Twig
{{ decorated.point() }}

GeocoderFieldTypePresenter::geocode()

The geocode method returns a geocoder point (as opposed to the above spatial point).

Returns: \Anomaly\GeocoderFieldType\GeocoderFieldTypePoint
Arguments
Key Required Type Default Description

$formatted

false

bool

none

Whether to use the formatted address instead of the input address.

Example
echo $decorated->geocode->city() . ', ' . $decorated->geocode->state();
Twig
{{ entry.location.geocode.city() }}, {{ entry.location.geocode.state() }}

Geocoder

This section will go over how to use the geocoder utility included with the geocoder field type.

To get started use the geocoder field type to create a new geocoder instance:

$geocoder = $fieldType->newGeocoder();

GeocoderFieldTypeGeocoder::convert()

The convert method will convert the provided address into a geocoded point object.

Returns: \Anomaly\GeocoderFieldType\GeocoderFieldTypePoint
Arguments
Key Required Type Default Description

$$address

true

string

none

The address to geocode. Partial addresses are supported as well.

Example
$point = $geocoder->convert('Davenport, IA');

GeocoderFieldTypeGeocoder::reverse()

The reverse method performs a reverse geocode lookup.

Arguments
Key Required Type Default Description

$collection

true

string

none

The collection to add the asset to.

Point

This section will go over how to use the geocoded point class included with the geocoder field type.

This particular class is returned by the presenter's geocode method:

$point = $decorated->geocode();

And an example of using the below methods in Twig:

{{ entry.location.geocode.state() }}

GeocoderFieldTypePoint::getResult()

The getResult returns the entire result array from Google's geocoding service.

Returns: array
Example
$result = $point->getResult();

GeocoderFieldTypePoint::address()

The address method returns the original input address used in the geocoder.

Returns: string
Example
$address = $point->address();

GeocoderFieldTypePoint::formatted()

The formatted method returns the formatted address string matched by the geocoder service.

Returns: string
Example
$match = $point->formatted();

GeocoderFieldTypePoint::route()

The route method returns the route component of the formatted address.

Returns: string
Example
$street = $point->route();

GeocoderFieldTypePoint::streetAddress()

The streetAddress method returns the street address (street number and route).

Returns: string
Example
$address1 = $point->streetAddress();

GeocoderFieldTypePoint::streetNumber()

The streetNumber method returns the street number of the formatted address.

Returns: string
Example
$house = $point->streetNumber();

GeocoderFieldTypePoint::city()

The city method returns the city component of the formatted address.

Returns: string
Example
$city = $point->city();

GeocoderFieldTypePoint::postalCode()

The postalCode method returns the postal code component of the formatted address.

Returns: string
Example
$zip = $point->postalCode();

GeocoderFieldTypePoint::state()

The state method returns the state component of the formatted address.

Returns: string
Example
$state = $point->state();

GeocoderFieldTypePoint::county()

The county method returns the county component of the formatted address.

Returns: string
Example
$county = $point->county();

GeocoderFieldTypePoint::country()

The country method returns the country name component of the formatted address.

Returns: string
Example
$country = $point->country();

GeocoderFieldTypePoint::countryCode()

The countryCode method returns the country code component of the formatted address.

Returns: string
Example
$country = $point->countryCode();

GeocoderFieldTypePoint::location()

The location method returns the location array component of the formatted address.

Returns: array
Example
$latitude = $point->location()['lat'];

GeocoderFieldTypePoint::latitude()

The latitude method returns the latitude component of the formatted address.

Returns: float
Example
$latitude = $point->latitude();

GeocoderFieldTypePoint::longitude()

The longitude method returns the longitude component of the formatted address.

Returns: float
Example
$longitude = $point->longitude();

GeocoderFieldTypePoint::point()

The point method returns a geometric Point instance to be used with the query builder if needed.

Returns: \Anomaly\GeocoderFieldType\Spatial\Point
Example
$location = $model->whereDistance('address', $geocoder->point(), '25 mi')->get();

Spatial

The geocoder field type comes with a set of optional features for creating and working with spatial data.

Query Builder

This section will go over how to use the spatial features added to Laravel's query builder.

EloquentQueryBuilder::selectDistance()

The selectDistance method allows you to select the calculated distance from a provided point. The returned value is in degrees.

Returns: \Anomaly\Streams\Platform\Model\EloquentQueryBuilder
Arguments
Key Required Type Default Description

$field

true

string

none

The geocoder field slug you would like to select distance for.

$point

true

mixed

none

An address, lat/lng array, or Point instance.

$formatted

false

bool

false

A flag to use the formatted point instead of the adjusted marker point.

$as

false

string

{$field}_distance

An optional name for the selected distance.

Example
use Anomaly\Streams\Platform\Support\Length;

$locations = LocationModel::selectDistance('address', 'Davenport, IA')->get();

foreach ($locations as $location) {
    echo (new Length($location->address_distance, 'deg'))->miles();
}

$closest = LocationModel::selectDistance('address', 'Davenport, IA')->orderBy('address_distance', 'ASC')->first();
Twig
{% set locations = entries('example', 'locations').selectDistance('address', 'Davenport, IA').get() %}

{% for location in locations %}
	{{ length(location.address_distance, 'deg').miles }}
{% endfor %}

{% set closest = entries('example', 'locations').selectDistance('address', 'Davenport, IA').orderBy('address_distance', 'ASC').first() %}

EloquentQueryBuilder::whereDistance()

The whereDistance method lets you add where restrictions based on distance.

Returns: \Anomaly\Streams\Platform\Model\EloquentQueryBuilder
Arguments
Key Required Type Default Description

$field

true

string

none

The geocoder field slug you would like to select distance for.

$point

true

mixed

none

An address, lat/lng array, or Point instance.

$operator

true

string

none

A valid where operator (<=, >=, etc).

$distance

true

mixed

none

The distance to use in the comparison. Can be interger or decimal.

$formatted

false

bool

false

A flag to use the formatted point instead of the adjusted marker point.

Example
$nearby = LocationModel::whereDistance('address', 'Davenport, IA', '15 mi')->get();
Twig
{% set nearby = entries('example', 'locations').whereDistance('address', 'Davenport, IA', '15 mi').get() %}

EloquentQueryBuilder::orWhereDistance()

The orWhereDistance distance is the same as the above method but uses an OR WHERE condition instead.