advertisement

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

Commonly-used place transforms are:

Transform Description
placeDetail returns the detail (street address, etc.) from a place value
placeCity Returns the city, town, or village from a place value
placeCounty Returns the county or district (smaller than state) from a place value
placeDistrict An alias for placeCounty
placeState Returns the state or province from a place value
placeProvince An alias for placeState
placeCountry Returns the country from a place value
placePostalCode Returns the postal code from a place value

Other place transforms are:

Transform Description
placeHasDetail Returns true if the given place has a detail component
placeHasCity Returns true if the given place has a city component
placeHasCounty Returns true if the given place has a county (AKA district) component
placeHasDistrict Returns true if the given place has a district (AKA county) component
placeHasState Returns true if the given place has a state (AKA province) component
placeHasProvince Returns true if the given place has a province (AKA state) component
placeHasCountry Returns true if the given place has a country component
placeHasPostalCode Returns true if the given place has a postal code component
placeLocale Returns the locale used by ORA when parsing a place

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:

Locale
Parameter
Description
? A special parameter value where ORA will choose a locale by searching for a country name at the end of the place value and by using other clues in the place value.

If ORA cannot determine the country, it will use the parser for the locale you have chosen as the Default Locale. If that property is set to "(none)", ORA will use it's generic place parser.

?locale A special parameter value where ORA will choose a locale by searching for a country name at the end of the place value and by using other clues in the place value. If ORA cannot determine the country, it will set the locale to the locale value that follows the "?" in the parameter.

So, for example, when using ?us, ORA will choose a locale by searching for a country name at the end of the place value and by using other clues in the place value. If ORA cannot determine the country, it will use the US parser, i.e., the result is the same as using "us" as the locale.

This is a good choice when most places in a collection are from a known country, but some places are not.

au A locale for Australia where place parts are divided according to an assumed sequence of city or town, county, state, and country. ORA uses a list of Australian states in its parser for this locale.
ca A locale for Canada where place parts are divided according to an assumed sequence of city or town, county, province, and country. placeProvince is a synonym for placeState, so you can use placeProvince or placeState to return the province value. ORA uses a list of Canadian provinces in its parser for this locale.
mx A locale for Mexico where place parts are divided according to an assumed sequence of city or town, state, and country. ORA uses a list of Mexican states in its parser for this locale. Mexico's post agency, Correos de México, does not offer an official list of state name abbreviations but ORA uses abbreviations based on suggestions from Wikipedia.
uk A locale for the United Kingdom where place parts are divided according to an assumed sequence of city or town, county, state, and country. For this locale, England, Northern Ireland, Scotland, and Wales are treated as states.
us A locale for the United States where place parts are divided according to an assumed sequence of city or town, county, state, and country. ORA uses a state list and a state-city-county list in its parser for this locale.

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.

Parameter Summary Note
c county bias Parsing option
t city or town bias Parsing option
s state bias Parsing option
a abbreviated value Output option
r raw value Output option
k known only Output option
d derived value Output option

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.

Field Name Residence
Value Halifax, Nova Scotia
Transform [Residence:placeCity:c]
Result
Transform [Residence:placeCounty:c]
Result Halifax County
Field Name Residence
Value Halifax, Nova Scotia
Transform [Residence:placeCity:t]
Result Halifax
Transform [Residence:placeCounty:t]
Result

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.

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

Place Value [Place:placeCounty]
Plymouth, Devon, EnglandDevon
Loughconeera, Co. Galway, IrelandCounty Galway
Boston, Suffolk, MASuffolk County
Grant, Allen, LAAllen Parish

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

Place Value [Place:placeCounty:?:Co.:Par.]
Boston, Suffolk, MASuffolk Co.
Grant, Allen, LAAllen Par.

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.

Place Value [Place:placeCounty:?::]
Boston, Suffolk, MASuffolk
Grant, Allen, LAAllen

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.

Place Value [Place:placeCounty:k:d]
Springfield, PABradford County
Springfield, Delaware, PADelaware County

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

Place Value [Place:placeState]
Boston, MAMassachusetts
Boston, MassachusettsMassachusetts
Boston, MassMassachusetts
Boston, Mass, USAMassachusetts
Halifax, NSNova Scotia
Halifax, Nova ScotiaNova Scotia
Place Value [Place:placeState:a]
Boston, MAMA
Boston, MassachusettsMA
Boston, MassMA
Boston, Mass<, USA/td>MA
Halifax, NSNS
Halifax, Nova ScotiaNS

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

Place Value [Place:placeLocale] Country
Sydney, NSWauAustralia
Halifax, NScaCanada
Plymouth, EnglandukUnited Kingdom
Paris, France?(Generic)
Boston, MAusUnited States
On This Page