67. Find Nearest Point (Forward Geocode)
Returns the nearest point to a given address of interest (specified as address, locality, district, zipcode).
67.1 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. |
67.2 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://zonarsystems.net/interface.php?operation=forwardgeocode&action=showposition&format=xml&address=18200 Cascade Ave S&locality=Seattle&district=WA&zipcode=98188&external_id=1
Example Success Reply (XML):
Reply
Example request for more than one point (XML):
https://zonarsystems.net/interface.php?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):
Reply
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://zonarsystems.net/interface.php?operation=forwardgeocode&action=showposition&format=json&address=18200 Cascade Ave S&locality=Seattle&district=WA&zipcode=98188&external_id=1
Example Success Reply (JSON):
Reply
Example request for more than one point (JSON):
https://zonarsystems.net/interface.php?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
Example Success Reply (JSON):
Reply