Articles and Tutorials

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

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

This documentation refers to version 2 of the Point Of Interest (POI) web service. Major features introduced in version 2 include:

Address point searches
Fulltext searches
Filtering by ANZSIC categories
KML output support

While version 2 attempts to be backwards compatible with version 1 wherever practical, category filtering requires that category filters be specified using ANZSIC category codes. Mappings from version 1 categories to their ANZSIC equivalents can be found here .

The SmartFIND Point Of Interest (POI) 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 , KML , 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/v2/pois

Request URL

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

The default output format is text/xml.

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

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

Request URL Building Interface - Query Builder

The query builder interface can be found here . This is to help you to build the request url using the paramenters below.

Request Parameters

The following request parameters are supported.

Parameter	Value	Description
q	string	The 'q' parameter is used to specify a query string for fulltext searches.
lastWordWildcard	string	If set partial word matches are supported for the last term of the phrase provided for the 'q' parameter. If the 'q' parameter is not provided this modifier will have no effect.
address	string	Finds POIs using a structured address string. This should take the form <place name>, <suburb>, <town> OR <region>. For example Geosmart, Rosedale, 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. This parameter modifies the behaviour of the 'suburb' and 'locality' parameters. If neither the 'suburb' or 'locality' parameters are specified this modifier will have no effect.
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)	How far in metres from the specified location to search for the query terms.
category	string	The ANZSIC of a category to search within. If multiple categories are specified (category=451101&category=4513) results will be returned for entries that appear in any of the specified categories. ANZSIC 451101 and 4513 are Cafes and Caterers.
sort	(name, distance, relevance) For non-fulltext searches the default sort field is 'name', for fulltext searches the default sort field is 'relevance', when the radius parameter is provided the default sort field is 'distance'.	Sorts the results by the chosen criteria.
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.
mask	string	A hexadecimal bit mask specifying the fields to return in the response document. If not specified all fields are returned. The bit mask can be generated using the utility found here .

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.
queryTime	The time taken for the search to be executed.
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.
uuid	A unique identifier for the POI.
name	The name of the POI.
alternate_name	POI alternate name, if exists.
brand	The business brand, if exists.
shop_unit	The business unit number, if exists.
floor_level	The building floor level, if exists.
street	The street the POI is situated on.
building	The building name, if exists.
postcode	The POI postcode.
telephone	The telephone number of the business, if exists.
tel_after_hours	After hours telephone number for the business, if exists.
email	A contact email address for the business, if exists.
fax	The fax number for the business, if exists.
www	The URL of the business web site, if exists.
x	The x coordinate of the POI in the NZMG coordinate system.
y	The y coordinate of the POI in the NZMG coordinate system.
suburb	The suburb the POI is contained within.
district	The district the POI is contained within.
region	The region the POI is contained within.
island	The island the POI is contained within.
town	The town the POI is contained within.
full_address	A display label for the POI built from the POI name, suburb and town or region
lon	The POI's longitude coordinate in the WGS84 coordinate system.
lat	The POI's latitude coordinate in the WGS84 coordinate system.
categories	A space-separated list of categories the POI has been classified with.
type	A high-level classification for the POI. Currently 'business' is the only value supported. If the POI is not a business this value will be empty.
keywords	Textual keywords associated with the POI.
distance	Calculated distance in metres from the specified location if the radius search is requested.

Sample Response

 
<?xml version="1.0" encoding="UTF-8"?>
<pois queryTime="0.414" query="name=geosmart" start="1" totalResultsReturned="1" totalResultsAvailable="1">
    <poi>
      <uuid>2A793B4E80214E8AB64406A94485A96A</uuid>
      <name>Geosmart</name>
      <alternate_name></alternate_name>
      <brand>Car Navigation Support</brand>
      <shop_unit></shop_unit>  
      <floor_level>Level 1</floor_level>
      <street>29 Apollo Drive</street>
      <building>Apollo Tri-Centre</building>
      <postcode>0632</postcode>
      <telephone>+64 (9) 966 8730</telephone>
      <tel_after_hours></tel_after_hours>  
      <fax>+64 (9) 966 8721</fax>
      <email></email>
      <www>www.geosmart.co.nz</www>
      <x>2665166.0228426300</x>
      <y>6493817.6945172900</y>
      <suburb>Rosedale</suburb>  
      <district>North Shore City</district>
      <region>Auckland</region>
      <island>North Island</island>
      <town>North Shore</town>
      <full_address>Geosmart, Rosedale, North Shore</full_address>
      <lon>174.732881900000</lon>  
      <lat>-36.744111400000</lat>
      <categories>692208</categories>
      <type>business</type>
      <keywords>PROFESSIONAL SCIENTIFIC TECHNICAL SERVICES CAR NAVIGATION SUPPORT</keywords>
      <description></description>       
    </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.

API Quick Links