Geocoding Web Service
The Geocoding Web Service allows users to find associated geographic coordinates from street addresses.
The web service can be accessed using any client software that supports standard HTTP POST requests and results are returned in CSV format.
Authentication
The Geocoding web service is a commercial service. If you would like to use the service but do not have a subscription contact sales@geosmart.co.nz.
The service uses HTTP Basic Authentication. When using the service non-interactively the username and password may be specified in the URL before the hostname component:
http://<user>:<password>@spatial.geosmart.co.nz/geocoding
Request using Web Interface
The link below allows you to request a Geocoding job via HTML interface.
http://<user>:<password>@spatial.geosmart.co.nz/geocoding.html
Request URL
HTTP POST method is used to create a new Geocoding job.
http://<user>:<password>@spatial.geosmart.co.nz/geocoding
Request POST Data
| Parameter | Type | Description |
|---|---|---|
addresses | string | CSV addressses. Each row defines street address to be geocoded. The values are:
|
Sample Address Data 1
"ID 1", 29 Apollo Drive North Shore 0632
Sample Address Data 2
"ID 1", "29 Apollo Drive", "North Shore", 0632
Sample Address Data 3
"ID 1", 29 Apollo Dr, Rosedale, North Shore, 0632
Sample Request Code in PHP
$addresses = <<<EOF
110,29 Apollo Drive North Shore 0632
"118-chch 111", 2 Buchan Street Sydenham Christchurch
111,"99 Albert Street", "Auckland"
112, "3 Tamamutu Street, Taupo", 3330
113,450 Moray Place Dunedin
114,419 Great South Road Penrose Auckland
EOF;
$options = array(
'http'=>array(
'method' => "POST",
'header' => "Accept-language: en\r\n"."Content-type: application/x-www-form-urlencoded\r\n",
'max_redirects' => 0,
'content' => http_build_query(array( 'addresses' => $addresses ) ) ));
$context = stream_context_create($options);
$response = @file_get_contents('http://<user>:<password>@spatial.geosmart.co.nz/geocoding',false,$context);
Sample Response Headers
HTTP/1.0 201 Created
Date: Fri, 12 Jun 2009 03:16:58 GMT
Location: /geocoding/1245
Content-Length: 15
Content-Type:
In the response headers, the Location header contains the URI for the job created. The completion time for each job varies, therefore the URI can be used to get the current status of the job.
Request Job Status
http://<user>:<password>@spatial.geosmart.co.nz/geocoding/<job id>
| Field | Type | Description |
|---|---|---|
| id | integer | A unique identifier |
| status | enum('pending','completed') | A status of the requested job: pending or completed |
| requested | datetime | The requested date and time |
| completed | datetime | The completed date and time |
| total | integer | The total number of the street addresses supplied |
| failed | integer | The number of geocoding failures including street data parsing errors and/or no matching address found |
| succeeded | integer | The number of successful matches |
| streetcentred | integer | The number of street centred addresses. This is when the address number could not be found so the result is geocoded to the centre of the given street. |
| input | URL | A link to view the input supplied |
| output | URL | A link to view the geocoded results |
Example XML Output
<geocoding>
<id>1245</id>
<status>completed</status>
<requested>2009-10-26 19:54:37</requested>
<completed>2009-10-26 19:56:33</completed>
<total>239</total>
<failed>29</failed>
<succeeded>190</succeeded>
<streetcentred>20</streetcentred>
<input>/geocoding/1245/input.csv</input>
<output>/geocoding/1245/output.csv</output>
</geocoding>
Request Job Input
http://<user>:<password>@spatial.geosmart.co.nz/geocoding/<job id>/input.csv
The URL is to view the input supplied for a previously requested job.
Request Job Output
http://<user>:<password>@spatial.geosmart.co.nz/geocoding/<job id>/output.csv
If a job is complete then the resulting output can requested using the above URL. If the job is incomplete, a 404 Not Found error will be returned.
| Column | Type | Description |
|---|---|---|
| id | string/integer | A unique identifier |
| input | string | A street address supplied |
| status | enum('PARSING FAILURE','FOUND','MATCHING FAILURE') | The status of the geocoding |
| score | integer | The score of the geocoding result out of 100. If the street name and number are matched, then it returns 100. The score is reduced for each address component that does not match. |
| number | alpanumeric | The street number |
| rd_name | string | The street name |
| suburb | string | The suburb name |
| town | string | The town name if exists |
| district | string | The district name |
| region | string | The region name |
| island | string | The island name |
| postcode | string | The postcode |
| x | numeric | The x coordinate of the address in the NZMG coordinate system. |
| y | numeric | The y coordinate of the address in the NZMG coordinate system. |
| lat | numeric | The latitude of the address |
| lon | numeric | The longitude of the address |
| reasons | string | The reasons for the score deductions. Seperated by "|". |
Sample CSV Output 1 - score 100
"id","input","status","score","number","rd_name","suburb","town","district","region","island","postcode","x","y","lat","lon","reasons"
"ID1","29 apollo drive North Shore","FOUND","100","29","Apollo Drive","Rosedale","North Shore","North Shore City","Auckland","North Island","","2665166","6493818","-36.74","174.73",""
Sample CSV Output 2 - street centred
"id","input","status","score","number","rd_name","suburb","town","district","region","island","postcode","x","y","lat","lon","reasons"
"ID2","29 apollo street Tauranga","FOUND","88","","Apollo Street","Otumoetai","Tauranga","Tauranga City","Bay of Plenty","North Island","3110","2787381","6386883","-37.68","176.14","29 is not found.|The centre of Apollo Street"
Sample CSV Output 3 - failed
"id","input","status","score","number","rd_name","suburb","town","district","region","island","postcode","x","y","lat","lon","reasons"
"ID3","29 apollo street christchurch","MATCHING FAILURE","0"