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. 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.

Table of Contents