PlaceFinder

Yahoo! PlaceFinder is a RESTful Web service, accessible using the following URI:

https://yboss.yahooapis.com/geo/placefinder?[parameters]

The PlaceFinder web service supports only the HTTP GET method. Other HTTP methods are not supported. You will also need to use Yahoo!’s OAuth authentication code to authenticate your API call to Yahoo!

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. For example:

``https://yboss.yahooapis.com/geo/placefinder?location= 1 Main
Street``
``https://yboss.yahooapis.com/geo/placefinder?q= 1 Main

Street``

Note

Parameters are evaluated in the following order: single-line (q), POI/AOI name (name), WOEID (woeid), multi-line (line1, line2, line3), fully parsed (house, street, unittype, unit, xstreet, postal, level4, level3, level2, level1, level0). Mixing parameters from different address formats is not supported. See Address Formats section for details.

Parameter Address Format Example Description
**``location or q
(query)``**
Free-Form Format 701 First Ave., Sunnyvale, CA 94089 A geographical location. It is recommended to use this parameter in your API request to get broader matches and results.
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 counrty 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.

Parameter Data Type Example Description Purpose
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).  
count integer 24 Number of results to return. Range is 1 to 100. Default is 10.  
count | integer | 24 | Number of results to return. Range is 1 to 100. Default is 10. | |

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

Supported Locales for PlaceFinder

PlaceFinder provides geocoding and reverse geocoding support in a number of locales. Results can be restricted to specific locales by using the locale parameter and the gflags control parameter. Here is a specific example:

https://yboss.yahooapis.com/geo/placefinder?q=Cambridge&gflags=L&locale=GB

North and South America

North and South America Country Code
BAHAMAS, THE BS
BRAZIL BR
CANADA CA
CAYMAN ISLANDS KY
FRENCH GUIANA GF
GUADELOUPE GP
MARTINIQUE MQ
MEXICO MX
SAINT BARTHELEMY BL
USA (including PUERTO RICO and US VIRGIN ISLANDS) US

Europe

Europe Country Codes
ANDORRA AD
ALBANIA AL
AUSTRIA AT
BELARUS BY
BELGIUM BE
BOSNIA AND HERZEGOVINA BA
BULGARIA BG
CROATIA HR
CZECH REPUBLIC CZ
DENMARK DK
ESTONIA EE
FINLAND FI
FRANCE FR
GERMANY DE
GIBRALTAR GI
GREECE GR
HUNGARY HU
ICELAND IS
IRELAND IE
ITALY IT
LATVIA LV
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACEDONIA MK
MOLDOVA MD
MONACO MC
MONTENEGRO ME
NETHERLANDS NL
NORWAY NO
POLAND PL
PORTUGAL PT
ROMANIA RO
RUSSIA RU
SAN MARINO SM
SERBIA RS
SLOVAKIA SK
SLOVENIA SI
SPAIN ES
SWEDEN SE
SWITZERLAND CH
TURKEY TR
UKRAINE UA
UNITED KINGDOM (including ISLE of MAN and CHANNEL ISLANDS) GB
VATICAN CITY VA

Asia

AsiaCountry Country Codes
HONG KONG-CHINA HK
INDIA IN
INDONESIA ID
MACAO-CHINA MO
SINGAPORE SG
TAIWAN TW
THAILAND TH

Middle East and Africa

Middle-East and Africa Country Codes
BAHRAIN BH
BOTSWANA BW
EGYPT EG
JORDAN JO
KENYA KE
KUWAIT KW
LEBANON LB
LESOTHO LS
MOROCCO MA
MOZAMBIQUE MZ
NAMIBIA NA
NIGERIA NG
OMAN OM
QATAR QA
REUNION RE
SAUDI ARABIA SA
SOUTH AFRICA ZA
SWAZILAND SZ
UNITED ARAB EMIRATES AE

Supported Response Formats

The PlaceFinder web service supports the following response formats:

Format How to Specify Description
XML default eXtensible Markup Language is an open standard specification for serializing structured data. See Example.
JSON Include J in the `flags Control Parameter <#control-parameters>`__. JavaScript Object Notation is a light-weight data interchange format, often used to serialize structured data. See Example.

Result Sub-Elements

The following tables describe the data elements in a response.

Result Sub-Elements

Element Data Type Description
quality Integer Quality of the result. Returned if P flag is not set. See Address Quality for details.
latitude Float Latitude of matched point in degrees, should be on a road center-line. Returned if P flag is not set.
longitude Float Longitude of matched point in degrees, should be on a road center-line. Returned if P flag is not set.
offsetlat Float Latitude of offset point in degrees, representing building/parcel setback from road center-line. Returned if P flag is not set and if Offset is greater than 0.
offsetlon Float Longitude of offset point in degrees, representing building/parcel setback from road center-line. Returned if P flag is not set and if Offset is greater than 0.
radius Integer Radius of matched area in meters. Returned if P flag is not set. Default if E flag is set, dynamic if not.
boundingbox Container Defines the extent of a box that encloses an area. Returned if P flag is not set and X flag is set. See Bounding Box Sub-elements for details.
name String POI/AOI name or Airport code. Returned if C flag is not set.
line1 String First line of address (House Street UnitType Unit). Returned if C flag is not set.
line2 String Second line of address (City State Zip in the US). Returned if C flag is not set.
line3 String Third line of address. Returned if C flag is not set.
line4 String Fourth line of address. Returned if C flag is not set.
cross String Cross streets nearest to location. Returned if C flag is not set and C gflag is set.
house String House number. Returned if C flag is not set.
street String/Container Street name or container for detailed street data (if S flag is set). Returned if C flag is not set. See Street Sub-elements.
xstreet String/Container Cross street name or container for detailed street data (if S flag is set). Returned if C flag is not set. See XStreet Sub-elements.
unittype String Unit type. Returned if C flag is not set.
unit String Unit/Suite/Apartment/Box. Returned if C flag is not set.
postal String Postal code. Returned if C flag is not set.
neighborhood String Neighborhood name. Returned if C flag is not set and G flag is not set. See Neighborhood Element for details.
city String City name. Returned if C flag is not set and G flag is not set.
county String County name (US/Canada only). Returned if C flag is not set and G flag is not set.
state String State/Province name. Returned if C flag is not set and G flag is not set.
country String Country name. Returned if C flag is not set and G flag is not set.
level4 String Level 4 area name (neighborhood). Returned if C flag is not set and G flag is set.
level3 String Level 3 area name (city/town/locality). Returned if C flag is not set and G flag is set.
level2 String Level 2 area name (county). Returned if C flag is not set and G flag is set.
level1 String Level 1 area name (state/province). Returned if C flag is not set and G flag is set.
level0 String Level 0 area name (country). Returned if C flag is not set and G flag is set.
countycode String County ISO 3166-2 code. Returned if C flag is not set.
statecode String State ISO 3166-2 code. Returned if C flag is not set.
countrycode String Country ISO 3166-1 code. Returned if C flag is not set.
level2code String Level 2 area ISO 3166-2 code. Returned if C flag is not set and G flag is set.
level1code String Level 1 area ISO 3166-2 code. Returned if C flag is not set and G flag is set.
level0code String Level 0 area ISO 3166-1 code. Returned if C flag is not set and G flag is set.
timezone String Timezone tz name. Returned if C flag is not set and T flag is set.
areacode String Telephone area code. Returned if C flag is not set and R flag is set.
uzip String Unique zip code. Returned if C flag is not set.
hash String A unique string derived from the returned address. Can be used by an app to index content based on the address.
woeid Integer Where On Earth ID for area. Returned if C flag is not set.
woetype Integer Where On Earth Place Type for area. Returned if C flag is not set.

Street & XStreet Sub-elements

Element Data Type Description
stfull String Street name/Cross Street . Returned if S flag is set.
stpredir String Street/Cross Street prefix directional. Returned if S flag is set.
stprefix String Street/Cross Street prefix type. Returned if S flag is set.
stbody String Street body/Cross Street. Returned if S flag is set.
stsuffix String Street/Cross Street suffix type. Returned if S flag is set.
stsufdir String Street/Cross Street suffix directional. Returned if S flag is set.

Bounding Box Sub-elements

Element Data Type Description
north Float North latitude in degrees. Range is -90.0 to 90.0
south Float South latitude in degrees. Range is -90.0 to 90.0
east Float East longitude in degrees. Range is -180.0 to 180.0
west Float West longitude in degrees. Range is -180.0 to 180.0

Address Quality

The value of an Address Quality element defines the granularity of the location described by an address. It is expressed as an integer between 0 and 99; higher values indicate more precision. Values of 80 or greater describe points; values less than 80 and 70 or greater describe lines; values less than 70 describe areas. A value of 0 indicates that no location could be extracted from the address data.

The response contains two Address Quality elements:

  • quality : Child element of Result . This element defines the quality of the address data for this result. If a response has mulitple Result elements, each will contain a quality element.

If the result quality is less than the best possible, then the accuracy of the result is less than requested. For example, suppose the input parameter is “1000 1st Ave Sunnyvale CA”, but the result is “998 1st Ave Sunnyvale CA”. In the response, the best possible result quality is 86 because closest street number found does not match the requested street number.

The following tables list the possible values for the Address Quality elements.

Points

Address Quality Value

Description
99 Coordinate
90 POI
87 Address match with street match
86 Address mismatch with street match
85 Address match with street mismatch
84 Address mismatch with street mismatch
82 Intersection with street match
80 Intersection with street mismatch

Line

Address Quality Value

Description
75 Postal unit/segment (Zip+4 in US)
74 Postal unit/segment, street ignored (Zip+4 in US)
72 Street match
71 Street match, address ignored
70 Street mismatch

Area

Address Quality Value

Description
64 Postal zone/sector, street ignored (Zip+2 in US)
63 AOI
62 Airport
60 Postal district (Zip Code in US)
59 Postal district, street ignored (Zip Code in US)
50 Level4 (Neighborhood)
49 Level4, street ignored (Neighborhood)
40 Level3 (City/Town/Locality)
39 Level3, level4 ignored (City/Town/Locality)
30 Level2 (County)
29 Level2, level3 ignored (County)
20 Level1 (State/Province)
19 Level1, level2 ignored (State/Province)
10 Level0 (Country)
9 Level0, level1 ignored (Country)
0 Not an address

Neighborhood Element

The neighborhood element describes an area that is contained within a larger administrative place (city). These areas may have fuzzy boundaries and no centralized government, so they should be used with care.

When the A gflags (gflags=A) is provided, the neighborhood element is populated with one or more neighborhood names. Neighborhood names are separated by the pipe symbol (vertical bar) and presented in order of significance. (That is, the first name is the primary neighborhood, the second name is the secondary neighborhood, and so forth.) Example: Downtown|Financial District.

Error Codes

The web service returns the following error codes in the response:

Error Description
0 No error
1 Feature not supported
2 Warning: Feature Not Supported
100 No input parameters
102 Address data not recognized as valid UTF-8
103 Insufficient address data
104 Unknown language
105 No country detected
106 Country not supported
107 Unput Parameter Too Long
108 No Airport Found
109 No DMA Code Found
110 Error Geocoding IP Address
2001 Error With Neighborhoods
2002 Error With WOE
2003 Error With Results Sizes
10NN Internal problem detected

Table: PlaceFinder Error Codes

In addition to errors specific to PlaceFinder that are listed above, BOSS Error Codes may also be returned.

Examples

XML is the default response format. This example shows the XML response for the location “701 First Ave, Sunnyvale, CA”.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=701+First+Ave,+Sunnyvale,+CA

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="location=San%20Francisco%2C%20CA">
  <results>
   <result>
    <quality>40</quality>
    <latitude>37.777119</latitude>
    <longitude>-122.41964</longitude>
    <offsetlat>37.777119</offsetlat>
    <offsetlon>-122.41964</offsetlon>
    <radius>8800</radius><name></name>
    <line1></line1>
    <line2>San Francisco, CA</line2>
    <line3></line3>
    <line4>United States</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal></postal>
    <neighborhood></neighborhood>
    <city>San Francisco</city>
    <county>San Francisco County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>94102</uzip>
    <hash></hash>
    <woeid>2487956</woeid>
    <woetype>7</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

To specify JSON format, include “J” in the flags parameter.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=San+Francisco,+CA&flags=J

Response Data:

{
 "bossresponse": {
  "responsecode": "200",
  "placefinder": {
   "start": "0",
   "count": "1",
   "request": "flags=J&location=San%20Francisco%2C%20CA",
   "results": [{
    "quality": "40",
    "latitude": "37.777119",
    "longitude": "-122.41964",
    "offsetlat": "37.777119",
    "offsetlon": "-122.41964",
    "radius": "8800",
    "name": "",
    "line1": "",
    "line2": "San Francisco, CA",
    "line3": "",
    "line4": "United States",
    "house": "",
    "street": "",
    "xstreet": "",
    "unittype": "",
    "unit": "",
    "postal": "",
    "neighborhood": "",
    "city": "San Francisco",
    "county": "San Francisco County",
    "state": "California",
    "country": "United States",
    "countrycode": "US",
    "statecode": "CA",
    "countycode": "",
    "uzip": "94102",
    "hash": "",
    "woeid": "2487956",
    "woetype": "7"
   }]
  }
 }
}

With free-form format, the entire address is specified in a single parameter. In this example, the address is “170 South Market St., San Jose, CA”.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=170+South+Market+St.,+San+Jose,+CA

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="location=170%20South%20Market%20St.%2C%20San%20Jose%2C%20CA">
  <results>
   <result>
    <quality>87</quality>
    <latitude>37.33263</latitude>
    <longitude>-121.889458</longitude>
    <offsetlat>37.332989</offsetlat>
    <offsetlon>-121.888977</offsetlon>
    <radius>400</radius>
    <name></name>
    <line1>170 S Market St</line1>
    <line2>San Jose, CA 95113-2307</line2>
    <line3></line3>
    <line4>United States</line4>
    <house>170</house>
    <street>S Market St</street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>95113-2307</postal>
    <neighborhood></neighborhood>
    <city>San Jose</city>
    <county>Santa Clara County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>95113</uzip>
    <hash>CAAC300CF45D6BF7</hash>
    <woeid>12797564</woeid>
    <woetype>11</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

In this example, the area of interest is “Yosemite National Park”.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?name=Yosemite+National+Park

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="name=Yosemite%2BNational%2BPark">
  <results>
   <result>
    <quality>63</quality>
    <latitude>37.84012</latitude>
    <longitude>-119.542854</longitude>
    <offsetlat>37.667542</offsetlat>
    <offsetlon>-119.805389</offsetlon>
    <radius>48900</radius>
    <name>Yosemite National Park</name>
    <line1>Yosemite National Park</line1>
    <line2>El Portal, CA 95318</line2>
    <line3></line3>
    <line4>United States</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>95318</postal>
    <neighborhood></neighborhood>
    <city>El Portal</city>
    <county>Mariposa County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>95318</uzip>
    <hash></hash>
    <woeid>55813396</woeid>
    <woetype>16</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

The woeid parameter specifies a unique ID for a geographic location. In this example, the woeid of 12797523 identifies the city Milpitas, CA.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?woeid=12797523

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="woeid=12797523">
  <results>
   <result>
    <quality>60</quality>
    <latitude>37.422676</latitude>
    <longitude>-121.8176</longitude>
    <offsetlat>37.422668</offsetlat>
    <offsetlon>-121.745209</offsetlon>
    <radius>12900</radius><name></name>
    <line1></line1>
    <line2>Milpitas, CA 95035</line2>
    <line3></line3>
    <line4>United States</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>95035</postal>
    <neighborhood></neighborhood>
    <city>Milpitas</city>
    <county>Santa Clara County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>95035</uzip>
    <hash></hash>
    <woeid>12797523</woeid>
    <woetype>11</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

In this example, the house number and street (100 Market St.) are in line1. The city and state (San Francisco, CA) are in line2.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?line1=100+Market+St.&line2=San+Francisco,+CA

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="line1=100%2BMarket%2BSt.&amp;line2=San%2BFrancisco%2C%2BCA">
  <results>
   <result>
    <quality>39</quality>
    <latitude>37.779162</latitude>
    <longitude>-122.420089</longitude>
    <offsetlat>37.779598</offsetlat>
    <offsetlon>-122.420143</offsetlon>
    <radius>10700</radius><name></name><line1></line1>
    <line2>San Francisco, CA</line2>
    <line3></line3>
    <line4>United States</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal></postal>
    <neighborhood></neighborhood>
    <city>San Francisco</city>
    <county>San Francisco County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>94164</uzip>
    <hash></hash>
    <woeid>2487956</woeid>
    <woetype>7</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

This example fetches information for the cross street (intersection) of “Market St at Montgomery St”. Note the keyword “at” in line1, indicating a cross street.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?line1=Market+St+at+Montgomery+St&line2=San+Francisco,+CA

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="line1=Market%2BSt%2Bat%2BMontgomery%2BSt&amp;line2=San%2BFrancisco%2C%2BCA">
  <results>
   <result>
    <quality>39</quality>
    <latitude>37.779162</latitude>
    <longitude>-122.420089</longitude>
    <offsetlat>37.779598</offsetlat>
    <offsetlon>-122.420143</offsetlon>
    <radius>10700</radius>
    <name></name>
    <line1></line1>
    <line2>San Francisco, CA</line2>
    <line3></line3>
    <line4>United States</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal></postal>
    <neighborhood></neighborhood>
    <city>San Francisco</city>
    <county>San Francisco County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>94164</uzip>
    <hash></hash>
    <woeid>2487956</woeid>
    <woetype>7</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

With a fully-parsed address, each address component is in a separate parameter, so delimiters are not needed. This example returns information for the following input address: “151 3rd St San Francisco CA 94103”.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?house=151&street=3rd+St&postal=94103&city=San+Francisco&state=CA&country=US

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="country=US&amp;postal=94103&amp;street=3rd%2BSt&amp;house=151&amp;state=CA&amp;city=San%2BFrancisco">
  <results>
   <result>
    <quality>87</quality>
    <latitude>37.785622</latitude>
    <longitude>-122.401207</longitude>
    <offsetlat>37.785912</offsetlat>
    <offsetlon>-122.400742</offsetlon>
    <radius>400</radius>
    <name></name>
    <line1>151 3rd St</line1>
    <line2>San Francisco, CA 94103-3107</line2>
    <line3></line3>
    <line4>United States</line4>
    <house>151</house>
    <street>3rd St</street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>94103-3107</postal>
    <neighborhood></neighborhood>
    <city>San Francisco</city>
    <county>San Francisco County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>94103</uzip>
    <hash>05B44B427D1BEC8F</hash>
    <woeid>12797154</woeid>
    <woetype>11</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

This locale parameter in this example is fr_FR, indicating the French language (fr) as spoken in France (FR). The default locale is en_US (English, United States). The location parameter is specifies a point of interest, “Eiffel Tower”.

Reminder: You may get diacritic or other accent marks on different languages. For example, <state>Île-de-France</state> in the response below.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=Eiffel+Tower&locale=fr_FR

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="location=Eiffel%20Tower&amp;locale=fr_FR">
  <results>
   <result>
    <quality>90</quality>
    <latitude>48.85873</latitude>
    <longitude>2.29382</longitude>
    <offsetlat>48.85873</offsetlat>
    <offsetlon>2.29382</offsetlon>
    <radius>1600</radius>
    <name>Tour Eiffel</name>
    <line1>Tour Eiffel</line1>
    <line2>75007 Paris</line2>
    <line3></line3>
    <line4>France</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>75007</postal>
    <neighborhood>7E Arrondissement</neighborhood>
    <city>Paris</city>
    <county>Paris</county>
    <state>Île-de-France</state>
    <country>France</country>
    <countrycode>FR</countrycode>
    <statecode></statecode>
    <countycode>75</countycode>
    <uzip>75007</uzip>
    <hash></hash>
    <woeid>22907017</woeid>
    <woetype>20</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

To specify the timezone and the telphone area code, include “T” and “R”, respectively, in the flags parameter.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=SFO&flags=TR

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="flags=TR&amp;location=SFO">
  <results>
   <result>
    <quality>62</quality>
    <latitude>37.614761</latitude>
    <longitude>-122.391876</longitude>
    <offsetlat>37.614761</offsetlat>
    <offsetlon>-122.391876</offsetlon>
    <radius>2600</radius>
    <name>San Francisco International Airport</name>
    <line1>San Francisco International Airport</line1>
    <line2>San Francisco, CA 94128</line2>
    <line3></line3>
    <line4>United States</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>94128</postal>
    <neighborhood>Millbrae</neighborhood>
    <city>San Francisco</city>
    <county>San Mateo County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <timezone>America/Los_Angeles</timezone>
    <areacode>650</areacode>
    <uzip>94128</uzip>
    <hash></hash>
    <woeid>12521721</woeid>
    <woetype>14</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

To get the bounding box coordinates in the response, specify “X” in the flags parameter.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=Moscone+Center&flags=X

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="flags=X&amp;location=Moscone%20Center">
  <results>
   <result>
    <quality>90</quality>
    <latitude>37.784161</latitude>
    <longitude>-122.401489</longitude>
    <offsetlat>37.784161</offsetlat>
    <offsetlon>-122.401489</offsetlon>
    <radius>100</radius>
    <boundingbox>
     <north>37.784611</north>
     <south>37.78371</south>
     <east>-122.400909</east>
     <west>-122.402069</west>
    </boundingbox>
    <name>George R Moscone Convention Center</name>
    <line1>George R Moscone Convention Center</line1>
    <line2>San Francisco, CA 94103</line2>
    <line3></line3>
    <line4>United States</line4>
    <house></house>
    <street></street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>94103</postal>
    <neighborhood></neighborhood>
    <city>San Francisco</city>
    <county>San Francisco County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>94103</uzip>
    <hash></hash>
    <woeid>23679434</woeid>
    <woetype>20</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

In this example, the gflags parameter includes “A” for the neighborhood and “C” for the cross streets.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=598+Market+Street+San+Francisco,+CA&gflags=AC

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="location=598%20Market%20Street%20San%20Francisco%2C%20CA&amp;gflags=AC">
  <results>
   <result>
    <quality>87</quality>
    <latitude>37.78886</latitude>
    <longitude>-122.40186</longitude>
    <offsetlat>37.788975</offsetlat>
    <offsetlon>-122.401955</offsetlon>
    <radius>400</radius>
    <name></name>
    <line1>598 Market St</line1>
    <line2>San Francisco, CA 94104-5322</line2>
    <line3></line3>
    <line4>United States</line4>
    <cross>Between Montgomery St/New Montgomery St and 2nd St</cross>
    <house>598</house>
    <street>Market St</street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>94104-5322</postal>
    <neighborhood>Financial District</neighborhood>
    <city>San Francisco</city>
    <county>San Francisco County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>94104</uzip>
    <hash>F3C2E686D28921A3</hash>
    <woeid>12797155</woeid>
    <woetype>11</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>

To perform reverse geocoding, specify the latitude and longitude for the location parameter, and include “R” in the gflags parameter. In this example, the latitude is 37.787082 and the longitude is -122.400929. The plus sign in the location is a URL-encoded space.

Request URI:

https://yboss.yahooapis.com/geo/placefinder?location=37.787082+-122.400929&gflags=R

Response Data:

<bossresponse responsecode="200">
 <placefinder start="0" count="1" request="location=37.787082%20-122.400929&amp;gflags=R">
  <results>
   <result>
    <quality>87</quality>
    <latitude>37.787102</latitude>
    <longitude>-122.400963</longitude>
    <offsetlat>37.787102</offsetlat>
    <offsetlon>-122.400963</offsetlon>
    <radius>400</radius>
    <name>37.787082 -122.400929</name>
    <line1>655 Mission St</line1>
    <line2>South Beach, CA 94105</line2>
    <line3></line3>
    <line4>United States</line4>
    <house>655</house>
    <street>Mission St</street>
    <xstreet></xstreet>
    <unittype></unittype>
    <unit></unit>
    <postal>94105</postal>
    <neighborhood>South Beach</neighborhood>
    <city>San Francisco</city>
    <county>San Francisco County</county>
    <state>California</state>
    <country>United States</country>
    <countrycode>US</countrycode>
    <statecode>CA</statecode>
    <countycode></countycode>
    <uzip>94105</uzip>
    <hash>2BB23C8D316A830E</hash>
    <woeid>12797156</woeid>
    <woetype>11</woetype>
   </result>
  </results>
 </placefinder>
</bossresponse>