Find Nearest Point (Forward Geocode)

Returns the nearest point to a given address of interest (specified as address, locality, district, zipcode).

Request Data

The following is a list of parameters that are required for this request.

Required Information
Name	Description
action	showposition
operation	forwardgeocode
format	xml or json
address	The street name part of the address of interest
locality	The locality part of the address of interest (ie. city)
district	The district part of the address of interest (ie. state)
zipcode	The zipcode part of the address of interest

 

Optional Information
Name	Description
external_id	An ID created by your program to reference a specific address. This is meant to be used used to identify the respective point to the address when the results are returned. If no value is given the program will auto-generate an ID for every address starting at 1 to n number of records processing. This value can be alpha-numeric. This value must be unique for every address. The program will return an error if they are not.

Data Returned

The point nearest to the given address of interest can be returned in XML or JSON format. If no nearby address is found a standard error XML document or JSON object is returned.

DTD

<!ELEMENT points (point*)>
<!ATTLIST points count CDATA #REQUIRED>
<!ELEMENT point (external_id, longitude, latitude, altitude, confidence)> <!ELEMENT external_id (#PCDATA)>
<!ELEMENT longitude (#PCDATA)>
<!ELEMENT latitude (#PCDATA)>
<!ELEMENT altitude (#PCDATA)>
<!ELEMENT confidence (#PCDATA)>

JSON

[{"external_id": int, "longitude": double, "latitude", double, "altitude": double, "confidence": int}]

Reply Data
Name	Description
external_id	The external ID of the respective address converted to point
latitude	The latitude of the returned point
longitude	The longitude of the returned point
altitude	The altitude of the returned point
confidence	The confidence of the returned point. This can be one of three values: Low, Medium, or High

Example request for one point (XML)

https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&operation=forwardgeocode&action=showposition&format=xml&address=18200 Cascade Ave S&locality=Seattle&district=WA&zipcode=98188&external_id=1

Example Success Reply (XML)

<?xml version="1.0"?>
<points ver="1.0" count="1"> 
 <point external_id="1"> 
 <longitude>-122.247559</longitude> 
 <latitude>47.438049</latitude> 
 <altitude>0.0</altitude> 
 <confidence>High</confidence> 
 </point> 
</points>

Example request for more than one point (XML)

https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&operation=forwardgeocode&action=showposition&format=xml&address[]=18200 Cascade Ave S
&locality[]=Seattle&district[]=WA&zipcode[]=98188&external_id[]=1&address[]=2151 E. Broadway Road
&locality[]=Tempe&district[]=AZ&zipcode[]=85282&external_id[]=2

Example Success Reply (XML)

<?xml version="1.0"?>
<points ver="1.0" count="2"> 
 <point external_id="1"> 
 <longitude>-122.247559</longitude> 
 <latitude>47.438049</latitude> 
 <altitude>0.0</altitude> 
 <confidence>High</confidence> 
 </point> 
 <point external_id="2"> 
 <longitude>-111.894889</longitude> 
 <latitude>33.407286</latitude> 
 <altitude>0.0</altitude> 
 <confidence>High</confidence> 
 </point> 
</points>

When requesting the data as JSON the only difference between the requests is that the format parameter is set to json.

Example request for one point (JSON)

https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&operation=forwardgeocode&action=showposition&format=json
&address=18200 Cascade Ave S&locality=Seattle&district=WA&zipcode=98188&external_id=1

Example request for more than one point (JSON)

https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&operation=forwardgeocode&action=showposition&format=json&address[]=18200 Cascade Ave S&locality[]=Seattle
&district[]=WA&zipcode[]=98188&external_id[]=1&address[]=2151 E. Broadway Road&locality[]=Tempe&district[]=AZ&zipcode[]=85282&external_id[]=2

When requesting more than one point there must be the same number of fields for every address part. For example, if you are requesting two points there must be two address fields, two locality fields, two district fields, two zipcode fields and two external_id fields (if external_id given for any one of the addresses).