The PlaceSearch operation returns the latitude and longitude for a given International Address, along with additional address and location information. It will attempt to geocode addresses at the property level, which is often a rooftop coordinate for some properties and then cascade to the next best available resolution such as the street, neighborhood, postal code, locality and so on. For non-address places such as streets, cities and postal codes, the coordinates will return a coordinate point that is commonly associated with the location or a centroid for the area.
URL Endpoints
- JSON
- XML
HTTP GET Request Help Page
HTTP POST Request Help Page
PlaceSearch Inputs
| Name | Type | Description |
|---|---|---|
| SingleLine ** | String | The full address on one line. |
| Address1 | String | Address Line 1 of the International Address. |
| Address2 | String | Address Line 2 of the International Address. |
| Address3 | String | Address Line 3 of the International Address. |
| Address4 | String | Address Line 4 of the International Address. |
| Address5 | String | Address Line 5 of the International Address. |
| Locality | String | The name of the distinct population cluster, such as a City, Town or other type of Municipality. |
| AdministrativeArea | String | The name of the administrative division. Commonly the primary division of a country, such as a State, Region, Province, County, Territory or Prefecture. |
| PostalCode | String | The postal code of the international address or its equivalent, such as a ZIP code (US), PLZ (DE, AU, and CH), PIN code (IN) and CAP (IT). It is recommended that the postal code be formatted to contain a strong resemblance to the proper country specific format, and that you do not precede the postal code with a country or region code. For example, use ‘09170’ instead of ‘FR-9170’. |
| Country * | String | The preferred name of the country or the ISO 3166-1 Alpha-2 Country Code or the Alpha-3 Country Code. Some alternate country names and spellings are supported, but the use of the common English spelled name or ISO2 country code is recommended for best results. |
| Boundaries | String | *Coming soon, not currently used – A comma-delimited list of coordinates that form a rectangular boundary in which to focus your search on. See “Boundaries” for more information. |
| MaxResults | String | Sets the maximum number of results the operation is allowed to return. Acceptable values range from 1 to 10. Defaults to 10 if no value is given. Note that by default, the operation will try to return a single best match, but if the result is ambiguous or if the SearchType ‘ALL’ is used then the operation will return no more than the given value. |
| SearchType | String | The name of the type of search you want to perform for the given address or place. Defaults to ‘BestMatch’ if no value is provided. See “Search Types” for more information. |
| Extras | String | A comma-delimited list of the extra features that you would like to enable on this search. See “Extras” for more information. |
| LicenseKey * | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/address-geocode/ |
** For best performance and results it is recommended to use parsed address inputs rather than a single line address. This is because there are less ambiguities with parsed inputs than SingleLine and the service has more options for trying to find a match.
PlaceSearch Outputs
- All of the response objects are contained within the SearchResponse object.
- SearchResponse
| Name | Type | Values | Description |
|---|---|---|---|
| SearchInfo | SearchInfo | Varies | Contains status, notes and warning information about the query as well as the number of locations returned. This object is always returned. |
| Locations | LocationInfo[] | Varies | Contains a list of LocationInfo objects. If a best match is found then the service will contain a single location. If a single best match cannot be found or if the ‘SearchType’ input value is set to ‘All’ then the list will contain no more than the maximum number of locations set by the ‘MaxResults’ input. |
| Error | Error | Varies | Error object indicating why the service could not return a result. See “Errors” page for more information. |
- SearchInfo
| Name | Type | Values | Description |
|---|---|---|---|
| Status | String | See “Status” for descriptions and possible values. | Indicates if the service found one or more results or if it encountered an error when processing the query. |
| NumberOfLocations | String | Number Max Range of 0 – 10 |
Indicates the number of locations found for the query that will be listed in LocationInfo array Locations. The default maximum number of location returned by the service is 10; however, a lower value can be set in the ‘MaxResults’ input. |
| Notes | String or NULL |
See “Note Codes & Descriptions” for possible values and details. | Comma-separated list of descriptive note codes about the query. |
| NotesDesc | String or NULL |
See “Note Codes & Descriptions” for possible values and details. | Comma-separated list of descriptions that correspond to the Notes output. |
| Warnings | String or NULL |
See “Warning Codes & Descriptions” for possible values and details. | Comma-separated list of warning codes about the query. |
| WarningDesc | String or NULL |
See “Warning Codes & Descriptions” for possible values and details. | Comma-separated list of descriptions that correspond to the Warnings output. |
- LocationInfo
| Name | Type | Values | Description |
|---|---|---|---|
| PrecisionLevel | String | Number Ranges 1 – 16 |
Indicates how precise the coordinates are. Levels range from 1 – 16. The higher the number the higher the precision. See “Precision Levels” for more details. |
| Type | String | See “Types” for possible values and details. |
Indicates what type of location the coordinates are for. For example, the location may be for an address, thoroughfare, locality or postal code. |
| Latitude | String | Varies | The latitude of the location. A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. |
| Longitude | String | Varies | The longitude of the location. A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. |
| AddressComponents | AddressComponents | Varies | A name-value pair collection containing additional information about the location. See the “AddressComponents” table and the list of Components for more details. |
- AddressComponents
| Name | Type | Values | Description |
|---|---|---|---|
| PremiseNumber | String or NULL |
Varies | The number associated with the property. Also known as the Address, Street or House number. |
| Thoroughfare | String or NULL |
Varies | The name of the thoroughfare. Also known as a street, road, highway, etc. |
| DoubleDependentLocality | String or NULL |
Varies | The name of the double dependent locality. |
| DependentLocality | String or NULL |
Varies | The name of the dependent locality. |
| Locality | String or NULL |
Varies | The preferred English name of the locality, such as a City, Town or other type of Municipality. |
| AdministrativeArea1 | String or NULL |
Varies | The name of the primary administrative division, such as a State, Region, Province, County, Territory or Prefecture. |
| AdministrativeArea1Abbreviation | String or NULL |
Varies | The abbreviated name of the primary administrative area. |
| AdministrativeArea2 | String or NULL |
Varies | The name of the secondary administrative division, such as a County or Region. |
| AdministrativeArea2Abbreviation | String or NULL |
Varies | The abbreviated name of the secondary administrative area. |
| AdministrativeArea3 | String or NULL |
Varies | The name of the third level administrative division, such as a Borough or District. |
| AdministrativeArea3Abbreviation | String or NULL |
Varies | The abbreviated name of the tertiary administrative area. |
| AdministrativeArea4 | String or NULL |
Varies | The name of the fourth level administrative division, such as a Ward or Quarter. |
| AdministrativeArea4Abbreviation | String or NULL |
Varies | The abbreviated name of the quaternary administrative area. |
| PostalCode | String or NULL |
Varies | The postal code of the international address. |
| Country | String or NULL |
Varies | The country |
| CountryISO2 | String or NULL |
Varies | The 2-letter country abbreviation. |
| CountryISO3 | String or NULL |
Varies | The 3-letter country abbreviation. |
| GoogleMapsURL ** | String or NULL |
Varies | Google Maps URL with the coordinates to the location. |
| PlaceName * | String or NULL |
Varies | County FIPS (Federal Information Processing Standard) code; used to uniquely identify counties across the US. |
| IsUnincorporated * | String or NULL |
Varies | Indicates if the coordinates are for an unincorporated area. Only appears for street level property matches (S). 1 – Indicates that the coordinates fall within the boundaries of a known unincorporated area. 2 – Indicates that the coordinates fall outside of the boundaries of a known area. |
| StateFIPS * | String or NULL |
2 Digit Number |
State FIPS (Federal Information Processing Standard) code; used to uniquely identity states. |
| CountyFIPS * | String or NULL |
3 Digit Number |
County FIPS (Federal Information Processing Standard) code;used to uniquely identify counties across the US. |
| CensusTract * | String or NULL |
6 Digit Decimal Number |
The census tract of the given address. A census tract is a statistical subdivision of a county. |
| CensusBlock * | String or NULL |
4 Digit Number |
The census block of the given address. A block is the smallest geographic unit used by the US Census. |
| CensusGeoID * | String or NULL |
15 Digit Number |
A Census based geographic identification code that uniquely identifies a geographic statistical area. |
| ClassFP * | String or NULL |
Alpha- Numeric |
A code that defines the current class of the geographic US location. |
| CongressCode * | String or NULL |
Varies | The congressional district number. |
| SLDUST * | String or NULL |
Varies | Current state legislative district upper (senate) chamber code. |
| SLDLST * | String or NULL |
Varies | Current state legislative district lower (house) chamber code |
| Timezone_UTC *** | String or NULL |
Number | The time zone in UTC offset format. |
** Only available when ‘URLs’ is included in the input value for Extras.
*** US Support Only. International
** Coming Soon **