Geofinder Documentation

Using Geofinder is simple and easy. The documentation below lists all of the tags, parameters, variables, etc available to you. Please contact support if you have questions or issues with Geofinder.

We have had reports that Geofinder does not work at Rackspace Cloud Hosting. A 620 Error Code is returned when trying to perform Geofinder searches. It appears Google’s Geocoding Service is blocking all geocoding requests coming from the Rackspace Cloud Hosting IP Addresses.

Installation

ExpressionEngine 2.x

  1. Copy EE2/geofinder to your third_party folder (e.g. /_your_ee_system_dir_/expressionengine/third_party/).
  2. Login to the ExpressionEngine Control Panel, go to Add-Ons → Modules.
  3. Find Geofinder in the list of available modules and click “Install”.

ExpressionEngine 1.x

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

Geofinder Template Usage

Geofinder provides five possible uses in templates:

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

Entries Search Form

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

Input Fields

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:channel:categories channel="bands|venues"}
<input type="checkbox" name="categories[]" value="{category_id}" /> {category_name}{/exp:channel: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.

Parameters

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"

Example Usage

{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:channel:categories channel="bands|venues"}
	<input type="checkbox" name="categories[]" value="{category_id}" /> {category_name}{/exp:channel:categories}
    <p><input class="btn" type="submit" value="Find Music Venues" /></p>
{/exp:geofinder:simple_form}

Location Results

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

Parameters

The Location Result tag extends the Channel 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 Channel Module documentation.

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"

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.

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.

channel (required)

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

channels="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"

orderby (optional)

Override the default orderby of distance.

orderby="entry_date"

sort (optional)

Override the default sort.

Variables

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

Channel Module Variables – EE docs

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}

Conditional Variables

if search_category_request

Lets you display content if the request includes search categories.

if no_results

if count

Variable Pairs

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

Channel Module Variable Pairs – EE docs

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}

Pagination

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

Channel Module Pagination – EE docs

Related / Reverse Related Entries

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

Channel Module Related / Reverse Related Entries – EE docs

Example Usage

{exp:geofinder:location_results channel="venues" status="open" limit="10" geoquery="{segment_4}" radius="{segment_5}" category="{segment_6}" latitude="{cf_venue_latitude}" longitude="{cf_venue_longitude}" distance_mode="miles" disable="member_data|category_fields|trackbacks"}
					<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>
				</tbody>
		</table>
		{/exp:geofinder:location_results}

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.

Input Fields

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>

Parameters

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"

Example Usage

{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 Results

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

Parameters

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}"

Variables

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

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}"

Conditionals

Example Usage

{exp:geofinder:member_results member_group="members" limit="20" radius="{segment_5}" geoquery="{segment_4}" latitude="cf_members_latitude" longitude="cf_members_longitude" distance_mode="km"}
						<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>
					</tbody>
		</table>
				{/exp:geofinder:member_results}

Geocode

Allows you to geocode addresses via templates. You can output the geocoded value in any format you can use in ExpressionEngine.

Parameters

geoquery (required)

Specify the URL segment that contains the geoquery.

geoquery="{segment_3}"

Variables

latitude

The returned latitude point of the geoquery.

{latitude}

longitude

The returned longitude point of the geoquery.

{longitude}

Conditionals

Example Usage

The code sample below produces the output in JSON, but XML or plain old HTML are possible too.

{ {exp:geofinder:geocode geoquery="{segment_3}"}
		"latitude": {latitude},
		"longitude": {longitude} 
		 {/exp:geofinder:geocode}
}

Changelog

1.0

1.1

1.2

1.2.1

1.2.4

1.3

1.3.1

1.3.2

2.0

2.1

2.1.1

2.1.2