Articles and Tutorials

Point of Interest (POI) Web Service - Version 1 API Documentation

The SmartFIND Point of Interest web service allows you to search for streets, businesses, and geographical features near a specified location. Proximity and category searches are also supported.

The web service can be accessed using any client software that supports standard HTTP GET requests and results can be returned in a number of text-based formats. XML, JSON, and serialized PHP are currently supported.

For a practical example of using this API in an Ajax application see Using the Point Of Interest (POI) Web Service with the Maps API

Authentication

The POI web service is a commercial service. If you would like to use the service but don't 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>@poi.geosmart.co.nz/pois

Request URL

http://poi.geosmart.co.nz/pois

The default output format is text/html. The HTML representation provides a search form for constructing queries and can be used to test the service interactively. Try the service: http://poi.geosmart.co.nz/pois

Alternative representations can be requested by appending the appropriate extension to the base URL:

text/xml
http://poi.geosmart.co.nz/pois.xml
text/javascript
http://poi.geosmart.co.nz/pois.json
text/php
http://poi.geosmart.co.nz/pois.php
text/html (list view)
http://poi.geosmart.co.nz/pois;list.html

Request Parameters

The following request parameters are supported.

Parameter Value Description
address string Finds POIs using a structured address string. This should take the form <place name>, <suburb>, <region>. For example GEOSMART, North Harbour, Auckland
name string Finds POIs with names that match the value of this parameter. Partial matches are supported, for example: 'geosmart' will match 'geosmart limited'.
street string The name of a street on which to search for POIs

if searching for a street use the name parameter instead.

suburb string The suburb to search within.
nearbySuburbs string If set will additionally return POIs in suburbs close to the specified suburb.
town string The town to search within.
district string The district to search within.
region string The region to search within.
locality string The web service will return any POI where the suburb, town, district, or region field matches the specified locality value.

If a locality string is specified it will override any individual fields provided.

x float The x coordinate of the starting location in the NZMG coordinate system.

If x and y parameters are provided they will override any locality parameters specified.

y float The y coordinate of the starting location in the NZMG coordinate system.
radius integer: (1-100000) default 2000 How far in metres from the specified location to search for the query terms.
category[] string The name of a category to search within. If multiple categories are specified (category[]=cafes&category[]=catering) results will be returned for entries that appear in any of the specified categories.
sort (name, distance) Sorts the results by the chosen criteria.
callback string When the results are requested in JSON format it can be useful to specify a callback function to pass the data to. If the callback function name is provided the JSON data will be wrapped in parentheses and the function name.
start integer: default 1 The starting result position to return (1-based).
maxResults integer: default 10 The number of results to return per query. The maximum value per query is 25.

If the query doesn't return many matches the actual number of results returned may be smaller than this value.

Response Fields

The following table describes all fields that may be returned in the query result list. Where a field value is unavailable for a particular POI it will be omitted from the response.

Field Description
query The query string that was provided for this search.
start The position of the first result in the result list.
totalResultsReturned Then number of query matches returned.
totalResultsAvailable Then number of query matches available.
id A unique identifier for the POI.
x The x coordinate of the POI in the NZMG coordinate system.
y The y coordinate of the POI in the NZMG coordinate system.
name The name of the POI.
street The street the POI is situated on (business POIs only).
suburb The suburb the POI is contained within.
town The town the POI is contained within.
district The district the POI is contained within.
region The region the POI is contained within.
telephone The telephone number of the business (business POIs only).
email A contact email address for the business (business POIs only).
www The URL of the business web site (business POIs only).
brand The business brand (business POIs only).
photo A photo of the POI.
categories A space-separated list of categories the POI has been classified with.

Sample Response

 
<?xml version="1.0" encoding="UTF-8"?>
<pois start="1" query="name=geosmart&locality=albany" totalResultsReturned="1" totalResultsAvailable="1">
  <poi>
    <id>17728</id>
    <x>2662001.023426</x>
    <y>6493692.9764988</y>
    <name>GEOSMART</name>
    <street>34 William Pickering Drive</street>
    <town>NORTH SHORE</town>
    <suburb>North Harbour</suburb>
    <district>North Shore City</district>
    <region>Auckland</region>
    <telephone>+64 (9) 415 3101</telephone>
    <brand>Car Navigation Support</brand>
    <categories>SHOPS APPLIANCES_ELECTRONICS</categories>
  </poi>
 
</pois>

Errors

The following error codes may be returned:

Code Description
400 Bad request. Parameters passed to the service were either incorrect or missing.
403 Forbidden. You don't have permission to access the service.
500 Service unavailable. An internal error prevented your request from being fulfilled.