Place Transforms

The transforms in this category manipulate place values using conventions for places based on a locale value.

Commonly-used place transforms are:

Other place transforms are:

Place Parts

ORA parses place values into place parts by splitting the values at each comma. For example, the place value "Boston, Suffolk, MA" has three parts: "Boston", "Suffolk", and "MA". The meaning of each part is locale-specific. Some locale-specific parsers may split parts into smaller parts when they determine that two or more place components are mixed in a single part.

Place Locales

ORA's place parser is customized by locale where a locale represents a geographic and cultural area and is often equivalent to a country. ORA chooses a locale based on an optional locale parameter and also uses the place value to determine the locale. So, for example, if a place value ends with "Nova Scotia", ORA will use the place parser customized for the ca (Canadian) locale.

The Default Locale preference on the OraSettings page determines the default locale when ORA is unable to determine a locale from the place value.

Tables

ORA's place parser uses tables to analyze and verify certain place parts. The tables are maintained on GitHub. You may review them and suggest changes via this page:
https://github.com/jfcardinal/ORA-Tables

Parameters and Parsing

The place transforms support many common parameters including a locale value and several keyword parameters. The parameters include parsing options that influence how ORA parses the place value into parts and output options that determine how ORA displays a place part.

Place values are only parsed once per locale even if there are multiple field references that use different place transforms. Any parsing-related options are applied when the first place transform triggers the place value to be parsed. You should specify the same locale and parsing options on all place transforms for the same field.

See the Parsing Options section for more details.

Locale Parameter

If no locale parameter is present, ORA defaults the locale parameter to ?. This is usually the best choice, however, if you use collections where all or most of the records are from one country but ORA cannot determine the locale for some reason, you may provide a locale parameter to influence or determine the locale chosen by ORA.

These are the supported locale parameter values:

While the general sequence of place parts is the same for all locales, there are differences in the parsing results. Those differences are mostly related to knowledge of city, county, and state names and other logic built-in to the locale-specific parsers.

Modifying Place Values

In some circumstances, you may find it useful to modify a place value before parsing it with any of the place transforms.

For example, if a record collection for a county in the United States omits the state name or abbreviation from all place values, the place parser will return more useful results if you append the state abbreviation to the place value. In the example below, assume that the Residence field includes the city and county only for a place in Oklahoma. The template uses an Assignment Reference with the replace transform to append the state abbreviation to the field.

[=:Residence:[Residence:replace:$:, OK]]
[Residence:placeCity]<, [Residence:placeCounty]>, [Residence:placeState]

Keyword Parameters

All the place transforms accept the locale parameter and one or more of the keyword parameters in the table below. You may specify zero or more keyword parameters. They are each a separate parameter, so separate multiple parameters with a colon as you do with positional parameters. Keyword parameters may be specified in any order, but if you specify conflicting keyword parameters, the last parameter will take precedence.

Parsing Options

A parsing option is a keyword parameter that influences how ORA interprets the place parts, deciding which is a city, county, state, etc. As described above, place values are only parsed once per locale even if there are multiple field references that use different place transforms. Any parsing-related options are applied when the first place transform triggers the place value to be parsed. Parsing options are ignored on any subsequent place transforms applied to the same field and using the same locale.

The following is an example of using parsing options incorrectly:

[Place:placeCity:t], [Place:placeCounty:c]

Given the template above, the Place field is parsed with parameter t in effect as part of processing the placeCity transform. The c parameter on the placeCounty transform is ignored because it is a parsing option and the place value was already parsed to produce the placeCity value.

[Place:placeCity:us:t], [Place:placeCounty:ca:c]

Given the template above, the Place field is parsed by the us parser with parameter t in effect as part of processing the placeCity transform. The Place field is parsed again by the parser and the c parameter on the placeCounty transform is honored.

Use all the same parsing options on all place transforms for a single field to avoid inconsistent results.

Output Options

An output option is a keyword parameter that influences the value that ORA returns from the Place Part transforms.

For example, the r keyword is an output option where placeState will return the text of the place part that ORA determined was the state (or province) value. By default, placeState will return the full name of the state even if an abbreviation or other alias was specified in the place field. If you specify the r keyword, ORA will return whatever was in the place field.

Parameter c: county bias

All the place transforms accept an optional keyword parameter c that influences the parsing of the place value such that ORA will favor detecting a county (or district) value over a city (or town) value. For most locales, ORA prefers the city over the county by default. For example, if the place value is "Halifax, Nova Scotia", [Place:placeCounty] (without ":c") returns an empty value because "Halifax" is interpreted as a city name. When using [Place:placeCounty:c], the return value is "Halifax County".

The place parsers for most locales default to "city bias" so you may want to add the c keyword if the records are from a locale where counties are included in records more often than city names. The us locale defaults to county bias.

c is a parsing option and is only applied by the first transform that triggers the parsing of a place value.

The county bias conflicts with the city bias and only one can be active at a time. If you supply both the c and t keyword parameters, the last one specified will be applied.

c is a keyword parameter and not a positional parameter. If you are chaining transforms and you do not want to specify the c parameter, you omit it and you do not have to specify an empty parameter in its place.

Parameter t: city or town bias

All the place transforms accept an optional keyword parameter t that influences the parsing of the place value such that ORA will favor detecting a city or town value over a county value. For the us locale, ORA prefers the county over the city by default. For example, if the place value is "Los Angeles, California", [Place:placeCity] (without ":t") returns an empty value because "Los Angeles" is interpreted as a county name. When using [Place:placeCity:t], the return value is "Los Angeles".

Most locales default to "city bias" so you don't need to specify the t parameter.

The us locale defaults to "county bias" so you may want to add the t keyword for a collection where most records do not include a county name.

t is a parsing option and is only applied by the first transform that triggers the parsing of a place value.

The county bias conflicts with the city bias and only one can be active at a time. If you supply both the c and t keyword parameters, the last one specified will be applied.

t is a keyword parameter and not a positional parameter. If you are chaining transforms and you do not want to specify the t parameter, you omit it and you do not have to specify an empty parameter in its place.

Parameter s: state bias

All the place transforms accept an optional keyword parameter s that influences the parsing of the place value such that ORA will favor detecting a state (or province) value over a county value when procssing the last part in the place value before the country name (if any). The state bias only matters when the place value does not contain a recognized state (or province) value.

The place parsers for most locales default to state bias off. You may choose to add the s keyword if the records are from a locale where states are included in most place values. The ca (Canada), mx (Mexico), and us (United States) locales default to state bias on.

s is a parsing option and is only applied by the first transform that triggers the parsing of a place value.

s is a keyword parameter and not a positional parameter. If you are chaining transforms and you do not want to specify the s parameter, you omit it and you do not have to specify an empty parameter in its place.

Parameter a: abbreviated value

The placeState, placeProvince, and placeCountry transforms accept an optional keyword parameter a where the transform will return the abbreviated state, province, or country name.

If you omit the a parameter, the transform will return the full name.

a is an output option only and does not affect parsing.

a is a keyword parameter and not a positional parameter. If you are chaining transforms and you do not want to specify the a parameter, you omit it and you do not have to specify an empty parameter in its place.

Parameter r: raw value

The placeCounty, placeDistrict, placeState, placeProvince, and placeCountry transforms modify the input value to produce a normalized value. If you want to extract the input value prior to normalization, add the r parameter to return the "raw" value.

If you specify the r parameter, the a, k, and d keywords are ignored.

r is an output option only and does not affect parsing.

r is a keyword parameter and not a positional parameter. If you are chaining transforms and you do not want to specify the r parameter, you omit it and you do not have to specify an empty parameter in its place.

Parameter k: known only

All the Place-related transforms accept an optional keyword parameter k which enables "known only" filtering where ORA attempts to ignore input values that do not match known good values.

k is an output option only and does not affect parsing.

The k parameter should be used with caution. Its behavior varies according to the locale. For the generic locale, and for most countries, it is not possible to verify place values and so the place transforms will always produce an empty value when using the k parameter.

k is a keyword parameter and not a positional parameter. If you are chaining transforms and you do not want to specify the k parameter, you omit it and you do not have to specify an empty parameter in its place.

Parameter d: derived value

The placeCounty, placeDistrict, and placeCountry transforms accept an optional keyword parameter d which enables "derived value" processing where ORA attempts to derive a value for an empty place part. So, for example, for the place "Boston, MA", [Place:placeCountry:d] will return "United States" because ORA derives the country name based on recognizing a US state abbreviation.

d is an output option only and does not affect parsing.

The d parameter should be used with caution. Its behavior varies according to the locale. The us locale will derive county names when given a city and state, but those counties are derived from modern jurisdictions and will not be correct for some historical places.

d is a keyword parameter and not a positional parameter. If you are chaining transforms and you do not want to specify the d parameter, you omit it and you do not have to specify an empty parameter in its place.

placeAddCountry:place-parameters

placeAddCountry appends the country name to a place value if (1) the place value does not have a country value and (2) the country can be derived.

placeAddCountry accepts the standard place parameters, including the locale parameter and the keyword parameters. placeAddCountry will attempt to derive the country value whether the d parameter is specified or not.

placeAddCountry is mostly intended for use by Search Target templates where the remote server returns better results when you specify country names in place filters.

placeDetail:place-parameters

placeDetail extracts the detail (street address, apartment number, or other text before the city name) from a place value.

placeDetail accepts the standard place parameters, including the locale parameter and the keyword parameters. placeDetail ignores the k parameter because placeDetails are not validated for any locale.

placeCity:place-parameters

placeCity extracts the city (or town or village) name from a place value.

placeCity accepts the standard place parameters, including the locale parameter and the keyword parameters. If you supply the k parameter, the result will usually be empty because ORA cannot validate city names for most locales. For the "us" locale, the result will be empty unless the city part is one of about 64 thousand known city values as of a circa 2015 database of cities and towns in the United States.

placeCounty:place-parameters:prefix-or-suffix:prefix-or-suffix

placeDistrict:place-parameters:prefix-or-suffix:prefix-or-suffix

placeCounty extracts the county or district name from a place value. placeDistrict is a synonym for PlaceCounty.

placeCounty accepts the standard place parameters, including the locale parameter and the keyword parameters.

If you specify the k parameter, the result will usually be empty because ORA cannot validate county or district names except for places in the "us" locale. For places in the "us" locale, ORA will attempt to determine if the county is valid using a circa 2015 database of places in the United States.

If you specify the d parameter and the place value does not contain a county component, the result will usually be empty because ORA cannot derive county or district names except for places in the "us" locale. For places in the "us" locale, if the place value does not contain a county but does contain a city and state, ORA will attempt to derive a county using a circa 2015 database of places in the United States.

In addition, placeCounty accepts one or two prefix-or-suffix parameters which it adds to the result based on rules that vary by locale. You specify the prefix-or-suffix parameters after any standard parameters, if any. You must specify the locale, at minimum, if you need to specify the prefix-or-suffix parameter(s).

For all locales except "us", PlaceCounty uses the first prefix-or-suffix parameter and it defaults to "County". PlaceCounty will add the text as a prefix or suffix if the input value includes the word "County" or an alias (Co., Cty., etc.) as a prefix or suffix. For the "us" locale, PlaceCounty uses two prefix-or-suffix values. The defaults are "County" and "Parish" where "Parish" is the default for Louisiana and "County" is the default for all other states.

The prefix-or-suffix parameters are positional parameters so you must supply them if you chain transforms after placeCounty. So, when chaining, you must supply the locale and two prefix-or-suffix parameters.

Examples

ORA detects the county names in the examples above and appends one of the default prefix-or-suffix values.

ORA detects the county names in the examples above and appends one of the given prefix-or-suffix values. The locale parameter is specified to avoid the prefix-or-suffix value being interpreted as a locale.

ORA detects the county names in the examples above and appends one of the given prefix-or-suffix values, both of which are empty values.

There are multiple cities named Springfield in Pennsylvania. When deriving a county value, ORA will use the first one it finds in a list that is sorted alphabetically, and a derived value is considered a "known value" so PlaceCounty returns "Bradford County" as in the first example. However, if the input value includes the county, as in the second example, ORA will not derive a value because one is already present. The k parameter is also present in the example and ORA determines that both Bradford County and Delaware County are valid for Springfield, Pennsylvania.

placeState:place-parameters

placeProvince:place-parameters

placeState extracts the state name from a place value. placeProvince is a synonym for PlaceState.

placeState accepts the standard place parameters, including the locale parameter and the keyword parameters.

If you specify the k parameter, the result will be empty except for locales where ORA has a table of state or province names.

placeState accepts the a keyword parameter to choose the abbreviated state name. If a is not specified, placeState returns the full value. For locales where ORA has a table of state or province names, the full value is taken from that table. For other locales, the full value is the input value. If ORA does not have a table that converts state names to abbreviations for the given country, the a parameter will have no effect and PlaceState will return the full value.

If you supply the k parameter, the result will be empty except in the locales listed above where the ORA parser includes a list of states.

Examples

placeCountry:place-parameters

placeCountry extracts the country name from a place value. ORA uses a list of 200+ country names, variations, and abbreviations to determine if the place value ends with a country name.

placeCountry accepts the standard place parameters, including the locale parameter and the keyword parameters.

If you specify the k parameter, the result will usually be the same because ORA only extracts a country name if it recognizes one as such.

placeCountry accepts the d parameter and will derive the country value if ORA recognizes a state or province value for a subset of countries.

placeCountry accepts the a keyword parameter to choose the abbreviated country name. If a is not specified, placeCountry returns the full name.

placePostalCode:place-parameters

placePostalCode extracts the postal code from a place value.

placePostalCode accepts the standard place parameters, including the locale parameter and the keyword parameters. If you supply the k parameter, the result will be empty because ORA cannot validate postal codes.

placeHasPart Transforms

placeHasDetail:place-parameters

placeHasCity:place-parameters

placeHasCounty:place-parameters

placeHasDistrict:place-parameters

placeHasState:place-parameters

placeHasProvince:place-parameters

placeHasCountry:place-parameters

placeHasPostalCode:place-parameters

There are several "placeHasPart" transforms where "Part" is replaced by a place part name such as "Detail", etc., as listed above. These transforms do not add any text to the output. Each returns true if the part indicated by the name is not empty. Otherwise, it returns false. These transforms are intended for advanced usage where you need to control output using conditional expressions.

The "placeHasPart" transforms accept the standard place parameters, including the locale parameter and the keyword parameters. Remember to specify any parameters that affect parsing because ORA has to parse the value in order to determine which parts it contains.

placeLocale:place-parameters

placeLocale returns the locale used by ORA when parsing a place. placeLocale is intended for advanced usage where you need to control output using conditional expressions.

placeLocale accepts the standard place parameters, including the locale parameter and the keyword parameters. Remember to specify any parameters that affect parsing because ORA has to parse the value in order to determine the locale.

Examples