Requests

Base URI

Yahoo! PlaceFinder is a REST Web service, accessible at the following URI:

http://where.yahooapis.com/geocode?[parameters]

The PlaceFinder Web service supports only the HTTP GET method. Other HTTP methods are not supported.

The appid parameter and at least one location parameter are required for all requests. Reserved characters in the parameters must be URL-encoded. All text in the request must be UTF-8 encoded.

Location Parameters

The location parameters indicate a place such as a street address. The format of these parameters can be free-form (one line), multi-line, or fully-parsed (house, street, unit, city, state, zip). For details, see Address Formats. The location parameters must be strings, unless noted otherwise. The following table lists the location parameters that can be passed to the Web service.

Location Parameter Address Format Example Description
location

or

q		 Free-Form Format 701 First Ave., Sunnyvale, CA 94089 A geographical location.
name N/A Yosemite National Park A Place of Interest (POI) name, Area of Interest (AOI) name, or airport code. See also POI and AOI Names. Ignored if location parameter is provided.
line1

or

addr		 Multi-line Format 701 First Ave. First line of address (street address or intersection). Ignored if location, name, or woeid parameter is provided.
line2

or

csz		 Multi-line Format Sunnyvale, CA 94089 Second line of address (city-state-zip in US). Ignored if location, name, or woeid parameter is provided.
line3 Multi-line Format EC1A 1BB Third line of address (postal code in UK). Ignored if location, name, or woeid parameter is provided.
house Fully-parsed Format 701 House number. Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
street Fully-parsed Format First Ave. Street name. Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
unittype Fully-parsed Format Apt Unit type, such as apartment (Apt) or suite (Ste). Ignored if location, name, woeid, or multi-line(line1/line2/line3) parameter is provided.
unit Fully-parsed Format 324 Unit/Suite/Apartment/Box. Ignored if location, name, woied, or multi-line (line1/line2/line3) parameter is provided.
xstreet Fully-parsed Format Mathilda Ave. Cross Street name. Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
postal Fully-parsed Format 94089 Postal code. Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
level4

or

neighborhood		 Fully-parsed Format SOMA Level 4 Administrative name (Neighborhood). Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
level3

or

city		 Fully-parsed Format Sunnyvale Level 3 Administrative name (City/Town/Locality). Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided. Do not specify level3 unless level1 or level0 is also specified; otherwise, erroneous results might be returned. For best results, specify at least level0 through level3.
level2

or

county		 Fully-parsed Format Santa Clara Level 2 Administrative name (County). Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
level1

or

state		 Fully-parsed Format CA Level 1 Administrative name (State/Province) or abbreviation (US only). Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
level0

or

country		 Fully-parsed Format USA Level 0 Administrative name (Country) or country code. Ignored if location, name, woeid, or multi-line (line1/line2/line3) parameter is provided.
woeid N/A 12797150 Where On Earth ID. Must be an integer. Ignored if location or name parameter is provided.

Control Parameters

The control parameters specify inputs other than location.

Control Parameter Data Type Example Description
appid string v0oWFBHV34 Required. The application ID. Grants authorization to use the web service.
locale string fr_CA The language and country. A two-letter ISO-639 major language code and a two-letter ISO-3166-1 alpha-2 country code, separated by either a hyphen or underscore. Default is en_US (English/US).
start integer 20 Index of first result to return. Range is 0 to 99. Default is 0.
count integer 24 Number of results to return. Range is 1 to 100. Default is 10.
offset integer 5 Location setback in meters, intended to approximate a building location offset from the road center-line. Range is 0 to 100. Default is 15.
flags string XRT String of concatenated characters that specify the data returned. The default value of this parameter is an empty string. The default return format is XML. See Flags Parameter.
gflags string AC String of concatenated characters that specify the geocoding performed. The default value of this parameter is an empty string. See Gflags Parameter.

Flags Parameter

The input parameter named flags determines which data elements are returned in the response. The value of the flags parameter is a string of characters. Each character is a capital letter that signifies the data to return. For example, the following flags parameter specifies that the bounding box (X), telephone area code (R), and timezone (T) are returned:

flags=XRT

The following table describes the characters allowed in the flags parameter:

Character in Flags Description
C Only return coordinate data and match quality elements; do not return address data elements.
E Do not return woeid element. This impacts the radius output.
G Return global area elements instead of US-specific elements.
J Return data in JSON format. Default format is XML. See Supported Formats..
P Return data in Serialized PHP format. Default format is XML. See Supported Formats..
Q Return nearest commercial airport code element for each result.
R Return telephone area code element for each result.
S Return detailed street attributes (Prefix, Body, Suffix, etc).
T Return timezone information element for each result.
X Return bounding box element for each area result.

Gflags Parameter

The input parameter named gflags affects how geocoding is performed for the request. The value of the gflags is a string of characters. Each character is a capital letter that controls an aspect of the geocoding. For example, the following gflags parameter specifies the return of neighborhood names (A) and the lookup of cross streets (C).

gflags=AC

The following table describes the characters allowed in the gflags parameter:

Character in gflags Description
A Return neighborhood names for each result.
C Look up cross streets for each result.
L Limit results to the locale country.
Q Quick mode, enable exact matches only for free-form input.
R Reverse geocode coordinates for each result. To perform reverse geocoding, specify the latitude and longitude in the location parameter. The response will include information such as the street address.

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.
Country USA (self-explanatory)
City, State Sunnyvale, CA (self-explanatory)
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

Supported Countries for Street-level Geocoding

The PlaceFinder Web service can return street-level information for locations in over seventy-five countries, listed as follows.

North and South America:

  • BAHAMAS, THE
  • BRAZIL
  • CANADA
  • CAYMAN ISLANDS
  • FRENCH GUIANA
  • GUADALOUPE
  • MARTINIQUE
  • MEXICO
  • SAINT BARTHELEMY
  • USA (including PUERTO RICO and US VIRGIN ISLANDS)

Europe:

  • ALBANIA
  • ANDORRA
  • AUSTRIA
  • BELARUS
  • BELGIUM
  • BOSNIA AND HERZEGOVINA
  • BULGARIA
  • CROATIA
  • CZECH REPUBLIC
  • DENMARK
  • ESTONIA
  • FINLAND
  • FRANCE
  • GERMANY
  • GIBRALTAR
  • GREECE
  • HUNGARY
  • ICELAND
  • IRELAND
  • ITALY
  • LATVIA
  • LIECHTENSTEIN
  • LITHUANIA
  • LUXEMBOURG
  • MACEDONIA
  • MOLDOVA
  • MONACO
  • MONTENEGRO
  • NETHERLANDS
  • NORWAY
  • POLAND
  • PORTUGAL
  • ROMANIA
  • RUSSIA
  • SAN MARINO
  • SERBIA
  • SLOVAKIA
  • SLOVENIA
  • SPAIN
  • SWEDEN
  • SWITZERLAND
  • TURKEY
  • UKRAINE
  • UNITED KINGDOM (including ISLE of MAN and CHANNEL ISLANDS)
  • VATICAN CITY

Asia:

  • HONG KONG-CHINA
  • INDIA
  • INDONESIA
  • MACAU-CHINA
  • SINGAPORE
  • TAIWAN
  • THAILAND

Middle-East and Africa:

  • BAHRAIN
  • BOTSWANA
  • EGYPT
  • JORDAN
  • KENYA
  • KUWAIT
  • LEBANON
  • LESOTHO
  • MOROCCO
  • MOZAMBIQUE
  • NAMIBIA
  • NIGERIA
  • OMAN
  • QATAR
  • REUNION
  • SAUDI ARABIA
  • SOUTH AFRICA
  • SWAZILAND
  • UNITED ARAB EMIRATES

Table of Contents