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 Parameter. | JavaScript Object Notation is a light-weight data interchange format, often used to serialize structured data. See Example. |
| Serialized PHP | Include P in the Flags Parameter. | A format for storing structured data in PHP. See Example. |
The Web service returns the following error codes in the response:
The following tables describe the data elements in a response.
| Element | Data Type | Description |
|---|---|---|
ResultSet |
Container | Top-level element for the response. Container for the remaining elements in this table. More than one result element may be returned if the given address is ambiguous. |
Error |
Integer | Error code. See Error Codes for possible values. |
ErrorMessage |
String | Error message (locale specific). |
Locale |
String | 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. |
Quality |
Integer | Best possible quality of the location parameter (input address). See Address Quality for details. |
Found |
Integer | Number of Result elements. |
Result |
Container | Contains elements associated with a single match result. See 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. |
| Element | Data Type | Description |
|---|---|---|
stfull |
String | Street name. Returned if S flag is set. |
stpredir |
String | Street prefix directional. Returned if S flag is set. |
stprefix |
String | Street prefix type. Returned if S flag is set. |
stbody |
String | Street body. Returned if S flag is set. |
stsuffix |
String | Street suffix type. Returned if S flag is set. |
stsufdir |
String | Street suffix directional. Returned if S flag is set. |
| Element | Data Type | Description |
|---|---|---|
stfull |
String | Cross Street name. Returned if S flag is set. |
stpredir |
String | Cross Street prefix directional. Returned if S flag is set. |
stprefix |
String | Cross Street prefix type. Returned if S flag is set. |
stbody |
String | Cross Street body. Returned if S flag is set. |
stsuffix |
String | Cross Street suffix type. Returned if S flag is set. |
stsufdir |
String | Cross Street suffix directional. Returned if S flag is set. |
| 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 |
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 ResultSet.
This element defines the best possible quality of the address specified by the input parameter.
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
Quality, 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 Quality for the input parameter is 87.
However, the 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 |
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 gflag 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.