Using Territories

Territories allow your locations to be returned as search results when they are possibly not physically present in a given searched area.  This is useful for creating sales territories, defining service areas or delivery boundaries for your locations.

Watch the video series on Territories below. This 10-part playlist dives into every territory feature in detail, starting with a simple example and overview.

Supported Territory Types

You can create territories from:

• Lists of Countries (as US,CA no spaces)

• Lists of States (as ST,ST no spaces)

• Lists of Cities (as City,ST no space)

• Lists of Counties (As the full numerical code, FIPS in the US)

• Lists of Postal codes

• Lists of Postal code prefixes (E.g. 532)

• Polygon bounded areas

• Service Radius

• All areas (global territory)

When a geographic search is performed, and a location includes a territory that coincides with that search, it is included with the search results regardless of the location’s latitude and longitude.

How Territory Search Works

When the user searches for a term, commonly a zip code, MetaLocator determines the city, state, country and county associated with that term. These are called administrative levels, and may have different names in different countries. For example, State is sometimes called Province and some countries do not have a “county” level. The administrative levels of the user’s search term are then compared to the values found in the territory fields in the data to find matches. The administrative levels of the user’s search term must fall within, or be equal to the location’s territory for a match to be found A user’s search term which is partially overlapping the territory will not match. For example, searching for a state name, such as “Wisconsin” and the territory includes a partial list of postal codes which fall within that state (E.g. 53211) will not return that result.

Adding Territory Fields

To create a territory-based search interface, the first step is to create a field to store the territory data.  Go to Fields, then click New in the toolbar.
 

Note the available options within the Territories option group.  In this example, we’ll create a State List Territory called StateTerritories.

Next, increase the “Field Length” to a length that will contain your list of territories.  For very large lists, use the “BLOB/TEXT” (binary large object) size.

Important note for very large territories: Excel has a cell limit of 32,000 characters. If your territories become very large and you are using excel to import and export data, be sure to consider the possibility that data may be truncated beyond 32,000 characters. Google Sheets supports 50,000 characters. Beyond those limits you can use Import with Append strategy to build very large territories.

Click Save to save field you have created. Repeat the process for every type of territory field you require.

Importing Territory Data

The next step is to add locations with territory data to your database.  This can be done by importing your data in bulk or by editing your locations one by one.  In this example, we’ll import the data in bulk.  We’ve prepared a CSV file with state territories as shown here:
 

Download the sample file for an example import file.

We can now import that file by going to Data then Import.  Click the Choose File… button and allow the import to proceed.  Observe that our individual locations now have lists of state abbreviations in our StateTerritories field.  You can see this list by editing a location, and scrolling to the bottom of the Edit Location screen to see the contents of  the StateTerritories field as shown here:

Be sure your Territory values are formatted according to the formatting below, taking care not to add spaces between values except as noted.

Data Format Requirements for Territories

Countries

US,CA

States

WI,IL,CA,VA 

Cities

Alberta,CA 
Portland,OR
Portland,MA

Counties

Counties are classified as Administrative Level 2. We support Administrative Level 2 territories in the US as County and in France as Department Codes. Be sure Get County and Neighborhood is enabled in your interface settings to support County searches.

US County Format Example

01007, 08017, 29151 

Include the full 5-digit FIPS code, including leading zeros. Do not include an underscore or tract-level FIPS codes.

France Department Code Example

01, 82, 973, 69D

Be sure to include the full department code including leading zeros.

Postal Codes

80205, 90210, 80201

Postal Code Prefixes

802, 902, 801

Radius

50

Global

1

Configuring the Interface For Territory Search

Now that data are imported, we are ready to create our Interface.  Do this by clicking Interfaces, then New, or you can modify an existing Interface.

Click over to the Territory Settings tab of the interface and set the following option, Enable Territories? : Yes 

Save your Interface and click Preview to see the results.  The default layout provides a postal code search.  Let’s try searching for 53202, a Wisconsin postal code.  Recall that none of our locations in the sample data are actually physically present in Wisconsin, yet we do have a single location that includes WI as a territory. Notice it appears in the search results as expected when searching for 53202, despite its physical address in Ohio.

Territory Options

When creating territories, you can designate how the search system should handle the territory results.  Under your Interface Territory Settings you will find a number of options, described here:

• Promote Territories:  This option sorts results that are matched by territory higher in the result list versus locations that matched based on distance or other criteria.

• Exclusive Territories: If territory results are available, display only territory results. Otherwise, display geographic (distance-based) results.

• Empty Territories.  This option disables territory results unless no geographic search results are found.  If a search does not return geographic results, then territory results will be included. If a search does return geographic results, then territory results will not be included. This can be used as a way to divide up “no results” searches.

• Include Only Territory Results in Search: Ignore the result’s geographic location and return results based only on territory values.

• Include Territories In Drop-downs:  Normally the drop-down lists are built from the location values.  In this setting, drop-down lists, such as State, are build using both the location’s State value and the value of any Territory State fields. If you are using territories, in most scenarios this should be enabled.

• Include Only Territory Values In Drop-downs:  Normally the drop-down lists are built from the location values.  In this setting, drop-down lists, such as State, are build using only value of any Territory State fields.  The values in the location’s State field are ignored.

• Default Record ID: When a search is performed, and no results are returned, this location should be returned as the sole result.

• Get County and Neighborhood:  Required when creating county-based territories. Be sure your location data is bulk geocoded with the same option enabled, labelled “Include county and neighborhood data”.

Postal Code Prefixes

When allowing users to match based on the postal code prefix, MetaLocator uses a two settings found under Advanced settings to enable and configure the prefix match.  Shown below, the “Allow Partial Match Keyword” must be enabled to support partial matches.  Additionally, the system will look for postal code territories with the length found in the “Partial Match Keyword Length” setting shown below.

Polygon Territories

Polygon territories allow you to specify a bounded polygon as a territory for a given location.  As of this writing, they can not be imported in bulk, only specified in the Control Panel.  To create a polygon territory for a location, first create a field under Fields.

Once created, open the location to which a polygon territory will be assigned.  The new polygon territory field will be found under Custom Fields and will be displayed as an interactive map.

Pan and zoom the map to the desired area for the territory.  Then click points on the map to set the boundaries in a clockwise manner, clicking the first marker as the last step to close the polygon.

Once the polygon has a shaded, filled area, save the location.  To re-draw the polygon, click “clear” below the map.  Only one polygon per territory field can be specified.  For locations with multiple polygon territories, create additional polygon territory fields as needed.

Presuming the Interface has Data Settings > Enable Territories? : Yes enabled, any search that resolves to a latitude/longitude contained within the boundaries of the drawn polygon (or polygons) this location will be returned as a result.

Radius Territories

Radius territories allow you to specify a circular range around which the location will be returned as a search result.  The field should contain the numerical value of miles or kilometers for the radius.  The units (KM or Miles) are determined by the Interface’s settings.  If it is set to use Miles, the values will be interpreted as miles.

Global Territories

Global territories are useful when a single result should be returned for all search geographies.  A global headquarters is an example where this might be useful.

Multiple Territory Fields & Interfaces

When you have multiple territory fields that might apply only to certain Interfaces you can limit the territory fields applicable to a given Interface by selecting those fields as shown below:

If empty, all territory fields are considered in the Interface.

Territories by Category

Territories can be defined to apply only to a specific category. In this scenario, a category commonly represents a product, service or therapy a location is contractually permitted to sell in a specific geography.

To enable territories by category, set this setting to “Yes”. Also be sure the Enable Territories is set to Yes.

The data for territories by category can be specified in the bulk import as shown below:

In the above example, the first row includes a state territory for any/all products for WI and MI, but only Camp products in IL and MN and only Hike products in PA. The values in the square brackets are category names and stateterritories is the field name of the territory field.

During import, be sure to leave the territories by category fields as “Create as Custom Field” as shown below:

Important: The row must include the categories for which any category-based territories are defined. E.g. to include a Camp territory, the row must also be in the Camp category.

The first row above appears as follows after the data is imported.

A few observations on how this affects search in this example:

• When a search is performed in Wisconsin or Michigan (WI,MI) this result is always returned.

  

  Another example:

  

• When a search is performed in IL or IN, and the user has selected Camp this result is returned.

  

• When a search is performed in PA, but the user has not selected Camp this result is not returned.

• When a search is performed in PA, and the user has selected Camp and Hike this result is returned.

  

Identifying Ambiguous Territory Values

When using City Territories or when you are not sure the exact territory value for a specific search, use the geocoding test tool to identify the value used by MetaLocator when checking the territory field. This will show the components returned for a specific search, which can then be used to refine territory values. This is especially helpful when the geocoder, or your data, might use an alternative spelling for a city, state or region name.

Excel Users: Important Note for County, Postal Code, Postal Code Prefix content:

Data handling in Excel can accidentally convert the list of entries to become a representation of a very long number. Spaces are allowable following the comma separating entries; e.g. 01003, 01025, 01031