Geofinder for ExpressionEngine Documentation

Using Geofinder is simple and easy. The documentation below lists all of the tags, parameters, variables, etc available to you. Please let us know if you have questions or see incorrect or missing information.

Installation

1. Purchase and download.
2. Unzip the downloaded file.
3. Copy lang.geofinder.php to your language directory (e.g. /_your_ee_system_dir__/language/english/).
4. Copy the geofinder folder to your modules directory (e.g. /_your_ee_system_dir__/modules/).
5. Login to the ExpressionEngine Control Panel, go to the Modules Tab.
6. Find Geofinder in the list of available modules and click “Install”.

Template Usage

Geofinder provides five possible uses in templates:

1. Simple Search Form for Entries Tag
2. Location Results Tag
3. Member Search Form
4. Member Results Tag
5. Geocode Tag

Simple Search Form for Entries

The Simple Search Form allows you to add a Geofinder Search form within your site for entries in weblogs, you could have a separate page for the search form, include the search form in every page of your site, or both!

You can now use categories in the search form as well.

{exp:geofinder:simple_form id="geofinder_form" result_page="/demos/geofinder/results"}
    <p><label for="find">Enter your street address, city or zip</label><input type="text" size="30" name="geoquery" value="Nashville, TN" id="find"/></p>
    <p><label for="radius">Select a radius</label>
	<select name="radius" id="radius">
            <option value="1">1 miles</option>
            <option value="5">5 miles</option>
            <option value="10">10 miles</option>
            <option value="50">50 miles</option>
	        <option value="100">100 miles</option>
            <option value="200">200 miles</option>
            <option value="300">300 miles</option>
	</select>
    </p>
    <p>Categories<br/>
    {exp:weblog:categories weblog="bands|venues"}
	<input type="checkbox" name="categories[]" value="{category_id}" /> {category_name}{/exp:weblog:categories}
    <p><input class="btn" type="submit" value="Find Music Venues" /></p>
{/exp:geofinder:simple_form}

Simple Search Form Input Fields

• geoquery
• radius
• categories
• user_lat (added to form automatically)
• user_lng (added to form automatically)

geoquery (required)

The input field that contains the address, city, state or zip

<p><label for="find">Enter your street address, city or zip</label><input type="text" size="30" name="geoquery" value="Nashville, TN" id="find"/></p>

radius (required)

The input or select field name that contains the radius value to search within (e.g. 5, 10, 100, 400 miles or kilometers).

<p><label for="radius">Select a radius</label>
    <select name="radius" id="radius">
            <option value="1">1 miles</option>
            <option value="5">5 miles</option>
            <option value="10">10 miles</option>
            <option value="50">50 miles</option>
	        <option value="100">100 miles</option>
            <option value="200">200 miles</option>
            <option value="300">300 miles</option>
    </select>
</p>

categories (optional)

The input or field name that holds your category values

<p>Categories<br/>
{exp:weblog:categories weblog="bands|venues"}
<input type="checkbox" name="categories[]" value="{category_id}" /> {category_name}{/exp:weblog:categories}

user_lat (added to form automatically)

The user_lat input is added to your form automatically. The purpose of the input is to allow for location aware searching (http://dev.w3.org/geo/api/spec-source.html). You must write your own Javascript code to populate this hidden input in order to use the functionality. Example iPhone usage (http://natural-logic.com/m).

A geoquery input value always overrides user_lat and user_lng.

user_lng (added to form automatically)

The user_lng input is added to your form automatically. The purpose of the input is to allow for location aware searching (http://dev.w3.org/geo/api/spec-source.html). You must write your own Javascript code to populate this hidden input in order to use the functionality. Example iPhone usage (http://natural-logic.com/m).

A geoquery input value always overrides user_lat and user_lng.

Simple Search Form Parameters

• id
• result_page

id (optional)

You can assign an id attribute to your form.

id="geofinder_form"

result_page (required)

Specify the result page used to display matching entries.

result_page="/demos/geofinder/results"

Location Results

The Location Results tag handles displaying entries based on the geoquery, radius and categories provided by a simple form or stand-alone using variables you supply.

{exp:geofinder:location_results weblog="venues" status="open" limit="10" geoquery="{segment_4}" radius="{segment_5}" category="{segment_6}" latitude="{cf_venue_latitude}" longitude="{cf_venue_longitude}" google_maps_api_key="XXXXXXXXXXXXXXXX" distance_mode="miles" disable="member_data|category_fields|trackbacks"}
	{if count == 1}
		<p>You searched for music venues within <strong>{radius}</strong> {distance_mode} of <strong>{geoquery}</strong>, <strong>{total_results}</strong> music venues were found.</p>
		<table cellspacing="0" cellpadding="0" width="100%">
			<thead>
				<tr><th>Venue</th><th>Website</th><th class="distance">Distance</th></tr>
			</thead>
			<tbody>
	{/if}
				<tr><td><strong>{title}</strong><br/>{cf_venue_address}<br/>{cf_venue_city}, {cf_venue_state} {cf_venue_zip}</td><td><a href="{cf_venue_url}" title="{cf_venue_url}">{cf_venue_url}</a></td><td class="distance"><strong>{distance}</strong> {distance_mode}</td></tr>
	{if count == total_results}
			</tbody>
		</table>
	{/if}
	{if no_results}
			<p>We found no music venues based on your search.</p>
	{/if}
{/exp:geofinder:location_results}

Location Result Parameters

The Location Result tag extends the Weblog module class so many of the parameters, variables, etc are the same as the Weblog module. In those cases, we simply refer you to the ExpressionEngine Weblog Module documentation.

• geoquery
• radius
• category
• latitude
• longitude
• distance_mode
• google_maps_api_key
• gmaps_country_code
• proxy
• weblog
• status
• limit
• author_id
• backspace
• cache=‘yes’ refresh=‘60’
• disable
• group_id
• paginate
• show_expired
• show_future_entries

geoquery (required)

Specify the URL segment that contains the geoquery.

geoquery="{segment_4}"

radius (required)

Specify the URL segment that contains the radius.

radius="{segment_5}"

category (optional)

Specify the URL segment that contains the categories.

category="{segment_6}"

latitude (required)

Specify the custom field name for latitude.

latitude="{cf_venue_latitude}"

longitude (required)

Specify the custom field name for longitude.

longitude="{cf_venue_longitude}"

distance_mode (optional, default = “miles”)

Specify the distance mode for the search, either miles or km.

distance_mode="miles"

distance_mode="km"

google_maps_api_key (required)

Specify your Google Maps Api Key.

google_maps_api_key="{google_maps_api_key}"

gmaps_country_code (optional)

Allows you to implement country code biasing for geoqueries. Further information for country code biasing and a reference for valid country codes

gmaps_country_code="nz"

proxy (optional)

Specify the url to the proxy that will handle requests sent to Google’s Geocoding HTTP service. The proxy should return results in XML format and not alter the response from Google at all.

Use the format below when building your proxy.

proxy="http://yourdomain.com/google_geocode_proxy.php?output=xml&sensor=false&key="

The Google Maps API key you specify will be appended to the example proxy address above. The query will also be appended like “q=Nashville,TN”.

For searches that match UK postal codes, another GET param will be added “gl=gb” so ensure your proxy passes that on to Google’s Geocoding Service.

weblog (required)

From which weblog(s) to include results from. You can use the pipe character to specify multiple weblogs.

weblogs="venues|bands"

status (optional, default=“open”)

The status of entries to be included. Separate multiple status’ with the pipe character. Use “not” to exclude entries set with a given status

status="open"

status="open|draft"

status="not draft"

limit (optional)

Specify the number of entries to be limited to. If using pagination, you must specify a limit.

limit="10"

author_id (optional)

Limit the query by the member id of the entry’s author. You can use the pipe character to separate multiple values.

author_id="1"

backspace (optional)

Backspacing removes characters from the last iteration of the Location Results loop.

backspace="6"

cache, refresh (optional)

Enables tag caching. Refresh is the number of minutes to expire the cache.

cache="yes" refresh="60"

disable (optional)

The disable parameter allows you to turn off aspects of the tag you might not need.

disable="category_fields|member_data|pagination|trackbacks"

group_id (optional)

Allows you to specify from which member group ids you wish entries to be shown.

group_id="2|3|4"

group_id="not 2"

paginate (optional)

For use with pagination, allows you to specify where the paging links should be placed.

paginate="top"

paginate="bottom"

paginate="both"

show_expired (optional)

Have “expired” entries included in location search.

show_expired="yes"

show_future_entries (optional)

Have entries that have publish dates in the future to be included in location search.

show_future_entries="yes"

Location Result Variables

In addition to the variables listed below, you also have access to the standard Weblog module variables.

Weblog Module Variables – EE docs

• radius
• geoquery
• distance
• distance_mode
• query_lat
• query_lng

radius

The radius specified for the search.

{radius}

geoquery

The geoquery specified for the search.

{geoquery}

distance

The physical distance, in miles or kilometers, that this entry is from the geoquery value.

{distance}

distance_mode

The distance mode specified, miles or km.

{distance_mode}

query_lat

The latitude point of the geoquery.

{query_lat}

query_lng

The longitude point of the geoquery.

{query_lng}

Location Result Conditional Variables

• if search_category_request
• if no_results
• if count

if search_category_request

Lets you display content if the request includes search categories.

{if search_category_request}in categories: {search_categories backspace="2"}<strong>{search_category_name}</strong>, {/search_categories}{/if}

if no_results

{if no_results}<p>We found no music venues based on your search.</p>{/if}

if count

{if count == 1}<tr><td colspan="3">{total_results} You searched for "{geoquery}" in categories {search_categories backspace="2"}<strong>{search_category_name}</strong>, {/search_categories} within {radius} {distance_mode}.</td></tr>{/if}

Location Result Variable Pairs

In addition to the variable pair listed below, you also have access to the standard Weblog module variable pairs.

Weblog Module Variable Pairs – EE docs

• search_categories

search_categories

The search categories included by the simple search form. The backspace parameter is supported to use with search_categories. Only the search category name is returned.

{search_categories backspace="2"}<strong>{search_category_name}</strong>, {/search_categories}

Location Result Pagination

Pagination is supported and works exactly like it does for the Weblog module.

Weblog Module Pagination – EE docs

Location Result Related / Reverse Related Entries

Related and reverse related entries are supported and work exactly like they do for the Weblog module.

Weblog Module Related / Reverse Related Entries – EE docs

Member Search Form

The Member Search Form allows you to add a Geofinder Search form within your site for members. It allows you to find members of your site using location based searching. The radius of the search supports miles or kilometers.

{exp:geofinder:member_form id="geofinder_form" result_page="/demos/geofinder-member/results"}
			<p><label for="find">Enter a city, state combination or zipcode</label><input type="text" size="30" name="geoquery" id="find"/></p>
			<p><label for="radius">Select a radius</label>
				<select name="radius" id="radius">
		            <option value="10">10 km</option>
		            <option value="50">50 km</option>
					<option value="100">100 km</option>
		            <option value="200">200 km</option>
		            <option value="300">300 km</option>
				</select>
			</p>
			<p><input class="btn" type="submit" value="Find Members" /></p>			
{/exp:geofinder:member_form}

Member Search Form Input Fields

• geoquery
• radius

geoquery (required)

The input field that contains the address, city, state or zip

<p><label for="find">Enter a city, state combination or zipcode</label><input type="text" size="30" name="geoquery" id="find"/></p>

radius (required)

The input or select field name that contains the radius value to search within (e.g. 5, 10, 100, 400 miles or kilometers).

<p><label for="radius">Select a radius</label>
	<select name="radius" id="radius">
	      <option value="10">10 km</option>
	      <option value="50">50 km</option>
		  <option value="100">100 km</option>
	      <option value="200">200 km</option>
	      <option value="300">300 km</option>
	</select>
</p>

Member Form Parameters

• id
• result_page

id (optional)

You can assign an id attribute to your form.

id="geofinder_form"

result_page (required)

Specify the result page used to display matching entries.

result_page="/demos/geofinder-member/results"

Member Results

The Member Results tag handles displaying members based on the geoquery and radius provided by the member search form.

{exp:geofinder:member_results member_group="members" limit="20" radius="{segment_5}" geoquery="{segment_4}" latitude="cf_members_latitude" longitude="cf_members_longitude" google_maps_api_key="{google_maps_api_key}" distance_mode="km"}
		{if count == 1}
		<p>You searched for members within <strong>{radius}</strong> {distance_mode} of <strong>{geoquery}</strong>, <strong>{total_results}</strong> members were found.</p>
		<table cellspacing="0" cellpadding="0" width="100%">
			<thead>
				<tr><th>Member</th><th>Website</th><th class="distance">Distance</th></tr>
			</thead>
			<tbody>
		{/if}
				<tr class="{switch="odd|even"}"><td><strong>{screen_name}</strong><br/>{location}</td><td><a href="{url}" title="{url}">{url}</a></td><td class="distance"><strong>{distance}</strong> {distance_mode}</td></tr>
		{if count == total_results}
			</tbody>
		</table>
		{/if}
		{if no_results}
			<p>We found no members based on your search.</p>
		{/if}
{/exp:geofinder:member_results}

Member Result Parameters

• member_group
• limit
• geoquery
• radius
• distance_mode
• latitude
• longitude
• google_maps_api_key

member_group (optional, default = “members”)

Specify the member group short name. Only one member group is currently supported.

member_group="members"

limit (optional, default = 20)

Specify the number of results to be limited to.

limit="20"

geoquery (required)

Specify the URL segment that contains the geoquery.

geoquery="{segment_4}"

radius (required)

Specify the URL segment that contains the radius.

radius="{segment_5}"

distance_mode (optional, default = “miles”)

Specify the distance mode for the search, either miles or km.

distance_mode="miles"

distance_mode="km"

latitude (required)

Specify the member custom field name for latitude.

latitude="{cf_members_latitude}"

longitude (required)

Specify the member custom field name for longitude.

longitude="{cf_members_longitude}"

google_maps_api_key (required)

Specify your Google Maps Api Key or the Global Variable name that holds it.

google_maps_api_key="{google_maps_api_key}"

Member Result Variables

In addition to the variables listed below, any standard member fields or custom member fields are also available for display.

• count
• total_results
• radius
• geoquery
• distance
• distance_mode
• query_lat
• query_lng
• switch

count

The record count.

{count}

total_results

The total number of results returned from the search.

{total_results}

radius

The radius specified for the search.

{radius}

geoquery

The geoquery specified for the search.

{geoquery}

distance

The physical distance, in miles or kilometers, that this entry is from the geoquery value.

{distance}

distance_mode

The distance mode, either “miles” or “kilometers”, specified for the search.

{distance_mode}

query_lat

The latitude point of the geoquery.

{query_lat}

query_lng

The longitude point of the geoquery.

{query_lng}

switch (optional)

Specify switch parameters for alternating class assignments

switch="{odd|even}"

Member Result Conditionals

• no_results

{if no_results}<p>We found no members based on your search.</p>{/if}

Geocode

Allows you to geocode addresses via templates. You can output the geocoded value in any format you can use in ExpressionEngine. The code sample below produces the output in JSON, but XML or plain old HTML are possible too.

{ {exp:geofinder:geocode geoquery="{segment_3}" google_maps_api_key="{google_maps_api_key}"}
		"latitude": {latitude},
		"longitude": {longitude} 
		{if no_results}
		"latitude": 0,
		"longitude": 0 			
		{/if} {/exp:geofinder:geocode}
}

Geocode Parameters

• geoquery
• google_maps_api_key

geoquery (required)

Specify the URL segment that contains the geoquery.

geoquery="{segment_3}"

google_maps_api_key (required)

Specify your Google Maps Api Key or the Global Variable name that holds it.

google_maps_api_key="{google_maps_api_key}"

Geocode Variables

• latitude
• longitude

latitude

The returned latitude point of the geoquery.

{latitude}

longitude

The returned longitude point of the geoquery.

{longitude}

Geocode Conditionals

• no_results

{if no_results}
		"latitude": 0,
		"longitude": 0 	
{/if}

Changelog

1.0

• Initial Release

1.1

• Added location search for members
• Added support for kilometers and miles
• Added geocoding tag

1.2

• Extends Weblog class: supports related/reverse related entries, pagination, caching
• Added multiple weblog search and category filtering
• Added new variable pair, {search_categories}
• Added new conditional variable {search_category_request}

1.2.1

• Bug fix for zip/postal code searches

1.2.4

• Added geocode caching

1.3

• Fixed pagination bug when using categories
• Added better geocoding handling for UK postal codes
• Added location aware (user_lat, user_lng) searching for location_results
• Added proxy param for location_results tag, useful in a shared hosting environment where Google Geocoding HTTP service can deny service because of other’s excessive use.

1.3.1

• Added new parameter gmaps_country_code. Usage details

1.3.2

• Fixed encoding issue with geocode tag.

Kick the Tires, Demo Geofinder →

Table of Contents