PostalAddress

These correspond to the "AddressLine" elements in xAL, which are used to hold unstructured text. This is an addendum to the structured values; when the address is formatted, the provided lines are prepended to the formatted version of the street component fields for Western countries, and appended for CJK countries. These lines are in display order. Formerly users of PostalAddress were discouraged from mixing address_line with structured address elements. Mixing is now encouraged if address_line has to be used at all.

Top-level administrative subdivision of this country. Examples: US state, IT region, UK constituent nation, JP prefecture.

Name corresponding to country code. Optional. This can usually be inferred from country_name_code.

xAL does not specify a scheme for country codes. We strongly recommend ISO 3166-1-alpha-2 (two letter codes, as used in DNS) if you use this field. (Use "GB", not "UK".)

Dependent locality or sublocality. Used for UK dependent localities, or neighborhoods or boroughs in other locations. If trying to represent a UK double-dependent locality, include both the double-dependent locality and the dependent locality in this field, e.g. "Whaley, Langwith".

Dependent thoroughfares are used to define UK-style dependent thoroughfares, and secondary streets in addresses in other locales, including intersections. Formatting is locale-dependent.

NEW: The firm or organization. This goes at a finer granularity than address_lines in the address. Omit if not needed.

Required to support the suppression of country names from formatted results for addresses within geo-politically disputed areas. Note that we cannot achieve this by not setting the country, as this would prevent us from selecting a suitable formatting template. Addresses converted from Oyster, by the standard conversion libraries, will have this field set if the address lies within a geo-politically disputed area (ie, contained within features of type TYPE_DISPUTED_AREA) even if the disputed area itself is not a visible part of the formatted address. An example of a disputed area is "No Man's Land" near Jerusalem which has the flag FLAG_NEVER_DISPLAY set for all its names. See: go/disputed-areas-2014 for more information.

Language of the address. May affect address formatting for multi- lingual countries. Also allows storing multilingual location names as repeated PostalAddress. Not in xAL. Use language codes which are accepted by i18n_identifiers::LanguageCodeCoverter::FromOther(). Examples include "en" and "de-CH".

Locality. This is something of a fuzzy term, but it generally refers to the city/town portion of an address. In regions of the world where localities are not well defined or do not fit into this structure well (for example, Japan), leave locality_name empty and use address_line. Examples: US city, IT comune, UK post town.

This corresponds to PostBoxNumber in xAL format. In xAL format, it's nested inside PostBox, which also contains a "Type" field to distinguish between PO Box, Private Bag etc. Current support in this proto is for PO Box only. Note that although this is modelled as a string, it should have the number only, with any necessary punctuation (such as "-"). For example, for "P.O. Box 123", this field would hold "123" - the template displaying this would prepend P.O. Box when formatting if necessary.

Despite the name, postal_code_number values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ".

Used for postal-code suffixes, such as the 4-digit extension of a US ZIP+4 code.

The "premise" is something like a house or building.

NEW: The recipient. This goes at a finer granularity than address_lines in the address. Not present in xAL. Omit if not needed.

This corresponds to the SortingCode sub-element of the xAL PostalServiceElements element. Use is very country-specific. Where it is used, the value is either a string like "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number alone, representing the "sector code" (Jamaica), "delivery area indicator" (Malawi) or "post office indicator" (e.g. Côte d'Ivoire).

Second-level administrative subdivision of this country. Examples: US county, IT province, UK county.

The "subpremise" is something like an apartment or suite. xAL offers more structured premise and subpremise values, but we don't.

Name of thoroughfare. Intersections should be represented with this field or address_line. Examples: "Amphitheatre Parkway", "N Shoreline Blvd & Charleston Rd"

Thoroughfare numbers (street numbers) can be very complex indeed. xAL defines fancy structures like "ThoroughfareNumberRange" to represent the details, but we haven't included that yet. It is worth noting that this needs to be a string, not a number. Example: "1600"