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



The ReverseSearch operation returns the address or place information for a given set of coordinates, along with additional address and location information. It will attempt to reverse geocode coordinates and return international addresses at the property level, which is often at the premise level resolution 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 returned by the service, the coordinates output in the response body will represent 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/ReverseSearch?Latitude={Latitude}&Longitude={Longitude}&SearchRadius={Search Radius}&Country={Country}&MaxResults={Max Results}&SearchType={Search Type}&LicenseKey={LICENSEKEY}

XML 

https://trial.serviceobjects.com/AGI/api.svc/xml/ReverseSearch?Latitude={Latitude}&Longitude={Longitude}&SearchRadius={Search Radius}&Country={Country}&MaxResults={Max Results}&SearchType={Search Type}&LicenseKey={LICENSEKEY}


HTTP GET Request Help Page


JSON  

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

XML    

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


HTTP POST Request Help Page


JSON  

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

XML    

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



ReverseSearch Inputs


Name

Type

Description

Latitude*StringThe 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

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. 

SearchRadiusStringThe maximum search radius distance set in kilometers. Defaults to 1. Maximum value of 50.
CountryStringThe 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.

MaxResults

StringSets the maximum number of results the operation is allowed to return. Acceptable values range from 1 to 10. 
SearchType*StringThe name of the type of search you want to perform for the given address or place. See "Search Types" 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

ReverseSearch 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 NULLSee "Note Codes & Descriptions" for possible values and details.Comma-separated list of descriptive note codes about the query.
NotesDescString or NULLSee "Note Codes & Descriptions" for possible values and details.Comma-separated list of descriptions that correspond to the Notes output.
WarningsString or NULLSee "Warning Codes & Descriptions" for possible values and details.Comma-separated list of warning codes about the query.
WarningDescString or NULLSee "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 NULLVariesThe preferred English name of the locality, such as a City, Town or other type of Municipality.
AdministrativeArea1String or NULLVariesThe name of the primary administrative division, such as a State, Region, Province, County, Territory or Prefecture.
AdministrativeArea1AbbreviationString or NULLVariesThe abbreviated name of the primary administrative area.
AdministrativeArea2String or NULLVariesThe name of the secondary administrative division, such as a County or Region.
AdministrativeArea2AbbreviationString or NULLVariesThe abbreviated name of the secondary administrative area.
AdministrativeArea3String or NULLVariesThe name of the third level administrative division, such as a Borough or District.
AdministrativeArea3AbbreviationString or NULLVariesThe abbreviated name of the tertiary administrative area.
AdministrativeArea4String or NULLVariesThe name of the fourth level administrative division, such as a Ward or Quarter.
AdministrativeArea4AbbreviationString or NULLVariesThe abbreviated name of the quaternary administrative area.
PostalCodeString or NULLVariesThe postal code of the international address.
CountryString or NULLVariesThe country
CountryISO2String or NULLVariesThe 2-letter country abbreviation.
CountryISO3String or NULLVariesThe 3-letter country abbreviation.
GoogleMapsURL **String or NULLVariesGoogle Maps URL with the coordinates to the location.
PlaceName *String or NULLVaries

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 NULLVaries

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 NULL2 Digit NumberState FIPS (Federal Information Processing Standard) code; used to
uniquely identity states.
CountyFIPS *String or NULL3 Digit NumberCounty FIPS (Federal Information Processing Standard) code; used to
uniquely identify counties across the US.
CensusTract *String or NULL6 Digit
Decimal Number
The census tract of the given address.
A census tract is a statistical subdivision of a county.
CensusBlock *String or NULL4 Digit NumberThe census block of the given address.
A block is the smallest geographic unit used by the US Census.
CensusGeoID *String or NULL15 Digit NumberA Census based geographic identification code that uniquely identifies a geographic statistical area.
ClassFP *String or NULLAlpha-NumericA code that defines the current class of the geographic US location.
CongressCode *String or NULLVariesThe congressional district number.
SLDUST *String or NULLVariesCurrent state legislative district upper (senate) chamber code.
SLDLST *String or NULLVaries

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