Address Formats

The location parameters can be specified in either free-form, multi-line, or fully-parsed format. The following sections describe each of these formats.

Free-form Format

In this format, all address components are combined in a single parameter: location. When necessary, use commas to separate the components. A free-form format may be one of the formats shown in the following table. Each of these formats may be followed by an optional country name or code.

Free-form Format Example Description
Latitude, Longitude 37.775391 -122.412209 Geographical coordinates. See Latitude and Longitude.
Airport code SFO See Airport Codes.
POI/AOI name Yosemite National Park See POI and AOI Names.
City Sunnyvale (self-explanatory)
Partial City Santa* A Partial City is a sequence of letters followed by an asterisk (*). The Web service will return up to 100 cities that begin with this sequence of letters, in probability order. Probability is determined from a number of factors, including popularity in current news articles and usage in non-location contexts.
State CA State or province result..
Country USA Country resutl.
City, State Sunnyvale, CA City, State resutl.
City (County), State Brentwood (Contra Costa), CA To disambiguate city/state, include the county in parenthesis. A city name is "ambiguous" if a state contains two cities with the same name. Do not add the county clause unless it is necessary. Use the county clause only if the PlaceFinder Web service returns a location in this format in a previous response.
POI/AOI name, City Washington Square Park, New York See POI and AOI Names.
POI/AOI name, City, State Washington Square Park, New York, NY See POI and AOI Names.
POI/AOI name, State Washington Square Park, NY See POI and AOI Names.
Line2 Sunnyvale, CA 94089 Second line of address (city-state-zip in US).
Line1, Line2 701 First Ave., Sunnyvale, CA 94089 First line of address (street address), a comma, and the second line of address (city-state-zip in US).
Line1 in/near Line2 First Ave. in Sunnyvale, CA 94089 Intersection of first line of address (street address) and second line of address (city-state-zip in US).

Multi-line Format

Multi-line addresses use two or three lines to represent an address. These are specified with the following location parameters: line1, line2, and line3. Typically, line1 contains a house number and street name, and optionally a cross street name; line3 contains City, State, and Postal code; line3 contains additional address data needed in certain countries. With multi-line addresses, delimiters are not necessary between address lines.

To disambiguate an address, indicate a cross street with one of the following:

  • &
  • at
  • and
  • near

The line1 parameter may be one of the following formats:

  • House Street
  • House Street UnitType UnitNumber
  • House Street at/near Street
  • House Street UnitType UnitNumber at/near Street
  • Street House
  • Street House UnitType UnitNumber
  • Street House at/near Street
  • Street House UnitType UnitNumber at/near Street
  • Street
  • Street &/and Street
  • Street at/near Street

The line2 parameter may be one of the following formats:

  • City
  • City, Postal code
  • City, State
  • City, State, Postal code
  • Postal code
  • Postal code, City

The line3 parameter may be one of the following formats:

  • Postal code
  • Postal code, Country
  • Country

Fully-Parsed Format

In a fully-parsed address, each address component is specified in a separate location parameter. The parameters that support fully-parsed addresses are listed in the "Address Format" column in the table under Location Parameters. No delimiters are needed to separate the address components.

For best results, provide level0 (country), level1 (state/province), level2 (county), and level3 (city). Providing level3 without level1 or level0 might produce erroneous results.

POI and AOI Names

Point of Interest (POI) and Area of Interest (AOI) names can be specified for some location parameters. POI and AOI names identify non-address places such as monuments, important buildings, parks, and bodies of water. The POI and AOI names may be followed by a city and/or state to disambiguate between places having the same name.

POI Examples:

  • Eiffel Tower
  • British Museum

AOI Examples:

  • Yosemite National Park
  • Lake Tahoe
  • Chinatown, San Francisco

Latitude and Longitude

Latitude and longitude can be specified for the location parameter. Latitude and longitude may be expressed as decimal degrees or degrees-minutes-seconds, with either leading or trailing directionals or leading signs. If directionals are provided, longitude may appear before latitude. If directionals are not provided, longitude may appear before latitude if it is outside the range -90 to 90. Otherwise, the latitude must appear first. Punctuation marks (commas, degrees, minutes, seconds) are ignored.

Examples:

  • 50.3 -120.5
  • 50.3, -120.5
  • -120.5 50.3
  • 50.3 N 120.5 W
  • 120.5 W 50.3 N
  • 50 18 0 -120 30 0
  • 50 18 0 N 120 30 0 W
  • 50° 18' 0" N 120° 30' 0" W

Airport Codes

An airport code can be specified for some location parameters. It is the 3-letter code printed on your luggage tags. For a full list, see IATA airport codes.

Examples:

  • SFO
  • LHR
  • BCN

Table of Contents