Page tree
Skip to end of metadata
Go to start of metadata



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

https://trial.serviceobjects.com/agi/api.svc/json/PlaceSearch?SingleLine={Singe Line Address}&Address1={Address 1}&Address2={Address 2}&Address3={Address 3}&Address4={Address 4}&Address5={Address 5}&Locality={Locality}&AdministrativeArea={Administrative Area}&PostalCode={Postal Code}&Country={Country}&Boundaries={Results Boundaries}&MaxResults={Maximum Results}&SearchType={Search Type}&Extras={Extras}&LicenseKey={LICENSEKEY}

XML 

https://trial.serviceobjects.com/agi/api.svc/xml/PlaceSearch?SingleLine={Singe Line Address}&Address1={Address 1}&Address2={Address 2}&Address3={Address 3}&Address4={Address 4}&Address5={Address 5}&Locality={Locality}&AdministrativeArea={Administrative Area}&PostalCode={Postal Code}&Country={Country}&Boundaries={Results Boundaries}&MaxResults={Maximum Results}&SearchType={Search Type}&Extras={Extras}&LicenseKey={LICENSEKEY}

HTTP GET Request Help Page


JSON  

https://trial.serviceobjects.com/AGI/api.svc/json/help/operations/PlaceSearch#response-json

XML    

https://trial.serviceobjects.com/AGI/api.svc/xml/help/operations/PlaceSearch


HTTP POST Request Help Page


JSON  

http://trial.serviceobjects.com/AGI/api.svc/json/help/operations/PlaceSearch_POST#request-json

XML    

http://trial.serviceobjects.com/AGI/api.svc/xml/help/operations/PlaceSearch_POST



PlaceSearch Inputs


Name

Type

Description

SingleLine **StringThe full address on one line.

Address1

String

Address Line 1 of the International Address.

Address2StringAddress Line 2 of the International Address.
Address3StringAddress Line 3 of the International Address.
Address4StringAddress Line 4 of the International Address.
Address5StringAddress Line 5 of the International Address.
LocalityStringThe 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 *StringThe 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.
BoundariesString*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.
MaxResultsStringSets 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.
SearchTypeStringThe 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.
ExtrasStringA 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/products/address-geocoding/address-geocode-international


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

LocationsLocationInfo[]VariesContains 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
NameTypeValuesDescription
StatusString

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.
NumberOfLocationsStringNumber
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.
NotesString or NULL
See "Note Codes & Descriptions" for possible values and details.
Comma-separated list of descriptive note codes about the query.
NotesDescString or NULL
See "Note Codes & Descriptions" for possible values and details.
Comma-separated list of descriptions that correspond to the Notes output.
WarningsString or NULL
See "Warning Codes & Descriptions" for possible values and details.
Comma-separated list of warning codes about the query.
WarningDescString or NULL
See "Warning Codes & Descriptions" for possible values and details.
Comma-separated list of descriptions that correspond to the Warnings output.


LocationInfo
NameTypeValuesDescription
PrecisionLevelStringNumber
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.
TypeStringSee "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.
LatitudeStringVariesThe latitude of the location.
A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point.
LongitudeStringVariesThe longitude of the location.
A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. 
AddressComponentsAddressComponentsVariesA name-value pair collection containing additional information about the location. See the "AddressComponents" table and the list of Components for more details.


AddressComponents
NameTypeValuesDescription
PremiseNumberString or NULLVariesThe number associated with the property. Also known as the Address, Street or House number.
ThoroughfareString or NULLVariesThe name of the thoroughfare. Also known as a street, road, highway, etc.
DoubleDependentLocalityString or NULLVariesThe name of the double dependent locality.
DependentLocalityString or NULLVariesThe name of the dependent locality.
LocalityString or NULL
VariesThe preferred English name of the locality, such as a City, Town or other type of Municipality.
AdministrativeArea1String or NULL
VariesThe name of the primary administrative division, such as a State, Region, Province, County, Territory or Prefecture.
AdministrativeArea1AbbreviationString or NULL
VariesThe abbreviated name of the primary administrative area.
AdministrativeArea2String or NULL
VariesThe name of the secondary administrative division, such as a County or Region.
AdministrativeArea2AbbreviationString or NULL
VariesThe abbreviated name of the secondary administrative area.
AdministrativeArea3String or NULL
VariesThe name of the third level administrative division, such as a Borough or District.
AdministrativeArea3AbbreviationString or NULL
VariesThe abbreviated name of the tertiary administrative area.
AdministrativeArea4String or NULL
VariesThe name of the fourth level administrative division, such as a Ward or Quarter.
AdministrativeArea4AbbreviationString or NULL
VariesThe abbreviated name of the quaternary administrative area.
PostalCodeString or NULL
VariesThe postal code of the international address.
CountryString or NULL
VariesThe country
CountryISO2String or NULL
VariesThe 2-letter country abbreviation.
CountryISO3String or NULL
VariesThe 3-letter country abbreviation.
GoogleMapsURL **String or NULL
VariesGoogle Maps URL with the coordinates to the location.
PlaceName *String or NULL
Varies

The name of the place that the coordinates are associated with. Most commonly the name of a municipality, city, town, village or community.

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 NumberState FIPS (Federal Information Processing Standard) code; used to
uniquely identity states.
CountyFIPS *String or NULL
3 Digit NumberCounty 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 NumberThe census block of the given address.
A block is the smallest geographic unit used by the US Census.
CensusGeoID *String or NULL
15 Digit NumberA Census based geographic identification code that uniquely identifies a geographic statistical area.
ClassFP *String or NULL
Alpha-NumericA code that defines the current class of the geographic US location.
CongressCode *String or NULL
VariesThe congressional district number.
SLDUST *String or NULL
VariesCurrent state legislative district upper (senate) chamber code.
SLDLST *String or NULL
Varies

Current state legislative district lower (house) chamber code

Timezone_UTCString or NULLNumberThe time zone in UTC offset format.

* Only available when 'Census' is included in the input value for Extras.

** Only available when 'URLs' is included in the input value for Extras. 


References



  • No labels