Postal Code Filter Pattern Matching

From AbleCommerce Wiki
Revision as of 17:32, 12 July 2009 by Loganr (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

When you define a zone in AbleCommerce, you have the option of setting a postal code filter. This would allow you to define a very specific area, perhaps to target a specific city. In early versions of AbleCommerce, the pattern matching is very simple. There is a single wildcard character * that can be used to match any value. For example 1234* would match 12340 through 12349.

Unfortunately, this wildcard matching proved to be too simple for some scenarios, especially with non-US postal codes. In response, support for a new style of postal code filter was added in AC7.0.1.

The descriptions and examples below will attempt to give a very basic introduction to using this pattern matching. If the explanations seem like gibberish, do not feel alarmed. Configuring regular expressions can be very complex, even for technically savvy people. If you need assistance, our community forum should be a helpful resource.

Common Pattern Elements

Element Description and Example
@ This symbol is not actually a regular expression element, but it is used by AbleCommerce to signal that the postal code filter uses the new pattern matching syntax. All patterns must begin with the @ symbol to activate the regular expression match.
| The vertical bar separates alternate values that should match.

@12345|12347 would match either 12345 or 12347.

Now let’s put the elements above together into some real world examples.

Schenectady, New York, USA

Suppose we are a merchant based in Schenectady, NY. We wish to create a zone to cover the city so that we can offer a special shipping method for customer pickup. We can use a regular expression pattern to do this:

Pattern: @^1234[0-9]$

Explanation: We used the square brackets to match a character range. This matches any value 12340 through 12349, which could be used to partially target the city of Schenectady, NY. Notice we have also used beginning and ending indicators so that we do not inadvertently accept the value 123456. Unfortunately, we have not yet recognized the values 12008, 12325, and 12345 that are also within city limits.

Pattern: @^1234[0-9]|12008|12325|12345$

Explanation: We combined the previous expression with the other ZIP codes using the vertical bar. This now matches all 5 digit ZIP codes assigned to Schenectady, NY. But wait… what if the customer puts in their plus 4 code? This pattern will not match the value 12345-0001.

Pattern: @^(1234[0-9]|12008|12325|12345)(-\d{4})?$

Explanation: We grouped the 5 digit ZIP codes with parenthesis. Then we included a second grouping. The grouping begins with a hyphen, meaning we expect the 5 digit zip code to have a hyphen before the plus 4. Then we have the \d element that matches any digit. Then we have the {4} quantifier to indicate there should be exactly 4 digits. The whole group is followed by the ? character which means it may or may not appear.

With this pattern we match the following values:

12345 12345-6789

But we do not match these values:

12350 123456789 12345-67890

Whistler, British Columbia, Canada

The regular expression pattern matching is particularly useful in non-US postal code matching because you can match specific sets of characters. Canada is notable because postal codes incorporate alphabetic as well as numeric values. Now suppose we wish to create a zone that specifically targets Whistler, BC.

Pattern:@^[A-Z][0-9][A-Z] [0-9][A-Z] [0-9]$

Explanation: This is a very basic example of a pattern that matches a Canadian postal code. The pattern is letter, digit, letter, digit, letter, digit. However it is not specific enough for our purpose.

Pattern: @^V0N1B[0-9]$

Explanation: This expression matches the range of postal codes from V0N1B0 through V0N1B9. That’s pretty good, but usually convention is to put a space in between the third and fourth character.

Pattern: @^V0N ?1B[0-9]$

Explanation: Now we have added an optional space, so a customer could enter V0N1B0 or V0N 1B0 and it would be a match. But we also want to include the Olympic Village in our zone, so we need to factor in one more postal code.

Pattern: @^V0N ?1B[0-9]|V0N ?2T0$

Explanation: Now our zone can identify all postal codes that belong to Whistler!

Multiple Patterns

All of the above examples used a single pattern. You can include multiple patterns in the postal code filter. A customer entry must match at least one of the patterns in order to be considered part of the zone. Separate multiple patterns with a semicolon, like so:


A more realistic example might be:


This would match any of the following codes:

12341, 12342, 12343, 12354, 12355, 12356, 12367, 12368, 12369