^
Top

Getting started with NSW Point

Complete the online access request form with the following information.

  • Organisation name
  • Organisation prefix
  • Organisation ABN
  • Organisation address
  • Users - a minimum of two are required including a main designated contact for the organisation
    • First name
    • Surname
    • Contact number
    • Position
    • Email
  • Application
    • Project name
    • Proposed application
    • Estimated number of transactions per day
    • Estimated launch date

Initial test and development access for NSW Point

The Spatial Services team will create an API key which will enable access to all endpoints for test and development (T&D) purposes. This will allow a 60-day trial period for clients to assess the services prior to using within an online application or form.

Throttle limits are set for each API key and will vary between T&D and PROD. Depending on the PROD application usage the throttle can be customised to meet requirements as needed.

User load testing

Any load testing during the development phase on the API services must be notified to Spatial Services at least two business days prior to commencement. A plan of dates, times (preferably outside normal business hours) and expected load must be included.

Production API key

Following the trial period, clients looking to implement NSW Point address validation into the production (PROD) application or form will complete the access request form with details as outlined above. A minimum of two contacts should be provided on the application together with the production application name, noting if the purpose is either T&D or PROD.

Best practice recommendations and implementation tips:

  • One API key per application or form is recommended. Each API key is issued with throttle limits and use in multiple applications can result in a service failure due to exceeding the limits. Using a unique API key for each application will also assist with implementation of Service Point.
  • Improve the response time and reduce requests on predictive services by implementing debounce where the request to NSW Point is not sent until there is a pause in the customer keystroke entry.
  • The predictive services were designed to not send a request to the API to provide suggestions until the end user enters at least four keystrokes.
  • Implement a ‘can’t find my address’ or similar feature to capture details where the address is not found form the predictive suggestions. This will allow the form or application to progress without impacting the customer, while still capturing the details through free text entry by the end user. An example is available in the sample form.
  • The predictive service allows clients to have additional administrative information about an address location included in the response called ‘outFields’ which are detailed in the output attributes topic. It is recommended that you only include the outFields in your request when they are deemed necessary for your business needs. Unnecessary inclusion of outFields that are not required has the potential to degrade service performance and API response times. Specific outFields are required when implementing NSW Point with Service Point.
  • Rotation of the API key every 12 months is recommended. This ensures currency of your nominated user details and improves security against the misuse of APIs.
  • Keep the nominated user details current to ensure notifications are received. There may be service enhancements, maintenance and outages which are communicated to nominated users.
  • Contact us if you have any questions about how to apply the API keys.

API Reference Guide

This page serves as a way to interact, test and demonstrate the service features
More information can be found in the model definitions below




Terminology

Common Definitions, Acronyms and Abbreviations

Term Definition
address component An individual element within an address. In NSW an address must contain the following minimum components to be considered valid: a unique street number (and sub-address number if appropriate), street name, suburb, state and postcode. An address may also include other components such site name, level number or sub-address type, eg unit
address validation Process of entering an address into an online form or application and retrieving the address data from NSW Point in a returned script with relevant components as requested.
ABS Australian Bureau of Statistics
ASGS Australian Statistical Geography Standard. Used by the ABS to define population and household regions
AV Address Verification
Address Widget NSW Point GUI element that can be embedded in an HTML web page. The widget integrates key NSW Point Web Services in a configurable format.
batch The process of undertaking bulk address verifications initiated though a single transaction. See Bulk Address Validation Services.
BAV Bulk Address Validation Services. A service provided by DCS Spatial Services to NSW Government agencies includes the assessment, cleansing, validation and geocoding of large volumes of address data.
coordinates Geocode location, expressed in decimal degrees format.
CSV Comma Separated Value. A file format used to store tabular data.
DPID Delivery Point Identifier. A unique 8 digit code used for postal delivery services.
endpoint The URL location for accessing a web service using a specific protocol and data format.
FSDF NSW Foundation Spatial Data Framework
function A web service that can be invoked with capabilities for searching and verifying addresses and providing other geospatial information.
fuzzy logic Predictive services access machine learning to provide the most accurate and logical suggestions based on the client input.
geocode Geographical co-ordinates; latitude and longitude
G-NAF The Geocoded National Address File. An index of physical Australian addresses, each with a geographic coordinate. Updated quarterly.
G-NAF Live The Geocoded National Address File. Updated nightly from the Australian State and Territory address authorities.
IAM Integrated Identity and Access Management.
jurisdiction A state/territory regional authority responsible for the provision of geospatial data.
JSON JavaScript Object Notation. Open-standard file format.
LGA Local Government Area
MailAddress A postal address data set accessed by Predictive services. Used to provide specifically postal address details, this service does not provide DPID.
mesh block Mesh Blocks are areas defined by the Australian Bureau of Statistics (ABS). Geoscape source mesh block data from the ABS and are the smallest geographical unit within the Australian Statistical Geography Standard (ASGS)
NAMF National Address Management Framework. A web service that supports the use of address information.
NCS NAMF Notification and Compliance Service
NWS NAMF Web Service. A web service that supports the use of address information within the National Address Management Framework.
OGC The Open Geospatial Consortium. A non-profit, international, voluntary consensus standards organisation that is leading the development of standards for geospatial and location based services.
PAF The Australia Post Postal Address File. A list of Australian addresses used for postal purposes. The PAF is only available through the AMAS (Address Matching Approval System) program and is used to support the efficient processing of mail through Australia Post’s operational network.
parse/parsing The process of separating individual components within a string of text into separate parts. For example, breaking up an address line into parts such as Number, Street Name, Street Type, Locality, State and Postcode amongst others.
parsed address An address that is presented is separate fields for each address component (not a single string)
predictive Enhances customer experience to provide suggested address listing for the user to select. Based on key stroke entry, the list returns the most logical suggested addresses.
Geoscape Geoscape Australia Limited, formerly known as Public Sector Mapping Agencies, is an unlisted public company wholly owned by the State, Territory and Australian Governments. It combines reliable spatial data from Australia’s governments with leading-edge technology to create national spatial information datasets.
single address transaction The validation of a single address using a combination of one or more NSW Point address-validation services.
Service Point Service Point is an anonymised transaction reporting service developed by Spatial Services to facilitate location based reporting for NSW Government. This service allows a client to capture metadata from a NSW Government transaction into Activity Register facility established within Service Point The metadata includes information such as: - transaction amount in dollars, - transaction type (eg driver's license renewal), and – anonymised address details (Mesh block, LGA, etc)
Further information can be found at website http://servicepoint.digital.nsw.gov.au
SA Statistical Areas. SA1, SA2, SA3 and SA4 are areas of population as defined by within the Australian Statistical Geography Standard (ASGS) as used by the ABS.
unparsed address An address that is presented as a single text string.
WFS Web Feature Service. An OGC defined interface for requesting geographical features across the web using platform independent calls.
WMS Web Map Service. An OGC defined interface for requesting Map images across the web using platform independent calls.
workflow Workflows encapsulate a set of functions, including parameter settings, so that they can be used (and re-used) in a simple manner in application programs.


Output Attributes

NSW Point Address Validation Services have been developed from a platform built upon Geoscape provided services and data. Where possible all attribution provided through our services is the same as that provided by Geoscape.
This is done to ensure a standardised and reliable addressing product that is consistent at both a state and a national level.
The following attributes may be included in NSW Point Single Address transaction and Bulk Address Validation Services.

Attribute Description
addressId A unique identifier (within an address dataset or file) for an address. Not a persistent identifier.
addressRecordType This field specifies whether the address returned is a Primary or Secondary address.
Primary - The address returned is a Primary address.
Secondary - The address returned is a Secondary address.
addressValidated True or false
aliasPrincipal Defines whether an address is an “alias” or “principal” address
cadastralIdentifier Cadastral identifier supplied by the jurisdiction responsible for the address
commElectoralName The name of the Commonwealth Electorate within which the address geocode resides.
commElectoralPid A unique identifier from the Geoscape dataset for the Commonwealth Electoral Area.
complexLevelIdentifier Complex level identifier (including any prefix and/or suffix) - This attribute should not be used as it is marked for deprecation to be replaced by complexLevelNumber.
complexLevelNumber Complex level number (including any prefix and/or suffix)
complexLevelType Complex level type (eg "Level", "Floor")
complexLevelTypeDescription Complex level type in full words (eg BASEMENT, LEVEL)
complexStreetName Complex street name
complexStreetNumber1 Complex first street number (including any prefix and/or suffix)
complexStreetNumber2 Complex second street number (including any prefix and/or suffix)
complexStreetSuffix Street suffix (eg Smith St "West")
complexStreetType Complex street type (eg "AV", "RD", "ST")
complexUnitIdentifier Complex unit identifier (including any prefix and/or suffix)
complexUnitType Complex unit type (eg "Unit", "Flat")
complexUnitTypeDescription Complex unit type in full words (eg UNIT, VILLA)
coorindates Geocode location. Latitude, longitude.
dataset A NAMF extension attribute applicable to Geoscape functions only. The name of the dataset used to obtain a result provided.
deliveryPointIdentifier Australia Post's Delivery Point Identifier or DPID
formattedAddress This is a NAMF extension parameter only available to Geoscape functions. The full address formatted into a single string.
geoDatumCode Geographic datum and/or coordinate reference system (eg "GDA94", "MGA50", "EPSG:4326")
geoEastWestCoordinate Coordinate value (eg longitude or easting)
geoFeature The physical or virtual reference of the geocode. Physical features associated with the address point may include mailbox, driveway, water meter, building. Virtual features are mathematically or geometrically derived spatial reference points such as the centroid of a lot or property.
geoNorthSouthCoordinate Coordinate value (eg latitude or northing)
geoType This attribute contains the level of the address match found. Possible values are:

ADDRESS - The result represents an address match at the Address level.
STREET - The result represents an address match at the Street level.
LOCALITY - The result represents an address match at the Locality
jurisdictionId A unique identifier from the Geoscape dataset that is sourced from the jurisdiction (State Government Agency) that supplied the address.
lgaShortName The shortened council name of the Local Government Area within which the address geocode resides.
lgaName The full council name of the Local Government Area within which the address geocode resides.
lgaPid A unique identifier from the Geoscape dataset for the Local Government Area.
localityAlias An unofficial name that is sometimes used to refer to a Locality. Alias Locality Names are not recognised as authoritative Locality Names, however they may be in common use. Localities may have multiple alias names but only one official (gazetted) name.
localityId​ An identifier from the Geoscape dataset is unique to a single locality (suburb)
localityName Locality name (eg Suburb)
localityNeighbour Surrounding neighbour localities listed (suburbs)
locationDescriptor A description of the position of the address relative to another physical site. eg. 3KM PAST THE BLACK STUMP SIGN
lotIdentifier A Lot number used as an address component (not supported by the NSW Addressing User Manual)
matchCertainty Returns the level of match between the input address and the address matched by the address verification service. Possible values are:

PARTIAL - The address returned partially matched the input address.
FULL - The address returned fully matched the input address.
matchCode This field is intended for diagnostic use only. This is a NAMF extension attribute only available in Geoscape functions that contains information on the quality of the address match returned by the address search process. It is only relevant to GNAF or GNAF Live. The string in the matchCode field contains match results for each NAMF Field in the format of Field Code followed by Match Type Codes. eg. SE:Y;UT:Y;UI:Y;LT:Y;CL:Y;LI:Y;NR:Y;SN:Y; etc.
matchQualityPercentage This is a NAMF extension parameter only available to Geoscape functions. This field contains a numeric value that indicates the quality of match found for the address. See Annex B for a description of match quality percentages.

As a general rule:
> 95 - indicates a real match or simple changes (such as locality/postcode mismatch or minor spelling errors),
90-95 - indicates a likely match but may need to be confirmed,
< 90 - typically require intervention to decide which candidate is correct. Whether to automatically accept matches or select options from a list depends on the business application.
mbId The unique identifier provided by the ABS for a feature within their mesh block dataset, grouped by the year of capture (eg asgsMain.2016.mbId: “10051731000”).
pafExpiryDate The last permissible date of use of a PAF deliveryPointIdentifier by end-users.
pafVersion Version of the PAF dataset the deliveryPointIdentifier is sourced from.
parcelId Only available through the NSW cadastral parcel service. Contains a string of all of the cadastral parcels associated with a single property (see propId) Formated as Lot / Section / Plan Label (eg 277/ /DP821883)
postalDeliveryNumber Postal delivery number (eg PO BOX "123")
postalDeliveryType Postal delivery type (eg "PO BOX" 123)
postcode Postcode
propId Only available through the NSW cadastral parcel service. Property NSW unique identifier provided from the land valuation database.
requestDate Formatted date and time address retrieved. YYYY-MM-DD HH:MM:SS
requestTimestamp System generated number.
sa1Id The unique identifier provided by the ABS for a feature within their Statistical Area 1 dataset, grouped by the year of capture (eg asgsMain.2016.sa1Id: “10301105814”).
sa2Id The unique identifier provided by the ABS for a feature within their Statistical Area 2 dataset, grouped by the year of capture (eg asgsMain.2016.sa2Id: “103011058”).
sa3Id The unique identifier provided by the ABS for a feature within their Statistical Area 3 dataset, grouped by the year of capture (eg asgsMain.2016.sa3Id: “10301”).
sa4Id The unique identifier provided by the ABS for a feature within their Statistical Area 4 dataset, grouped by the year of capture (eg asgsMain.2016.sa4Id: “103”).
siteName Site name (eg building name)
stateElectoralClassCode The class code of the State Electorate within which the address geocode resides.
stateElectoralName The name of the state electorate name which the address geocode resides.
stateElectoralPid A unique identifier from the Geoscape dataset for the State Electoral Area.
stateElectoralType The name of the state electoral assembly type which the address geocode resides. (Legislative Assembly or Legislative Council)
stateTerritory State or Territory
streetLocalityId An identifier from the Geoscape dataset that is attributed to the unique combination of a Street and a Locality e.g. George St Sydney NSW 2000. If a Street or Road, etc crosses a locality boundary, that segment receives a different street_locality_pid and treated as another street.
streetName Street name
streetNumber1 First street number (including any prefix and/or suffix)
streetNumber2 Second street number (including any prefix and/or suffix). Only include for a ranged address (eg 11-15 Smith St)
streetSuffix Street suffix (eg Smith St "West")
streetType Street type (eg "AV", "RD", "ST") abbreviated
streetTypeDescription Street type in full words (eg STREET, AVENUE, PLACE)


MatchCode Definitions

MatchCode is an attribute available to addresses sourced from GNAF and GNAF Live. It is intended for diagnostic use; to assist you in understanding how the service has matched each NAMF address field from the input during the validation process.

The matchCode value consists of a string of information in the format: NAMF FIELD: MATCH TYPE.
e.g. SE:Y;UT:Y;UI:Y;LT:Y;CL:Y;LI:Y;NR:Y;SN:Y;ST:Y;SS:N;LN:Y;PC:Y;SA:Y;

The tables below provide a breakdown of the codes used for both the NAMF Fields and MatchTypes:

NAMF Field Codes

Code Description
SE siteName
UT complexUnitType
UI complexUnitIdentifier
LT complexLeveltype
CL complexLevelNumber
LI lotIdentifier
NR streetNumber1, streetNumber2
SN streetName
ST streetType
SS streetSuffix
LN localityName
PC postcode
SA stateTerritory


Match Type Codes

Code Description
Y Yes, NAMF field was matched in the returned address.
N No, NAMF field was not matched in the returned address.
F Only streetNumber1 field was matched.
L Only streetNumber2 was matched.
A An alias match for the field was identified.
P A phonetic match for the field was identified.
S A phonetic match for an alias was identified.
G A neighbouring locality was matched.
B A phonetic match for a neighbouring locality was matched.


MatchQualityPercentage Definitions

MatchQualityPercentage is an attribute that can be returned with all NSW Point output addresses. It is a percentile value that indicates the quality of the address match.
The table below provides a breakdown of values to assist interpreting and ranking address matching results:

100% - Exact Matched Address
100 The returned address matches the input address with the following conditions:
  • Any of the following fields were not provided in the input address but were returned in the result
    • complexUnitType
    • complexLevelType
    • site_name
    • state
  • localityName is an alias but postcode is matched
  • streetNumber1 is matched
  • streetNumber2 is matched (or NULL in both the Request and result)
  • All other fields match (or NULL in both the Request and result)
96-99% - Highly Likely Match
99
  • Any condition covered by an Exact Match above
  • postcode was not provided in the input
  • complexLevelNumber was not provided but complexUnitIdentifier matches
98
  • Any condition covered by a 99% match
  • complexUnitType is not matched
  • complexLevelType is not matched
  • streetName or localityName is an alias
97
  • Any condition covered by 98%
  • localityName is an adjacent neighbour and result is best matched address
  • streetName is an alias and result is best matched address
  • streetType does not match, however, streetName and localityName is matched
  • A streetSuffix is additionally returned. No alternative streetSuffix for the address exist and streetName and localityName match
96
  • Any condition covered by 97%
  • siteName does not match
  • postcode does not match, however, state and localityName match and result is best matched address
  • streetName is a phonetic or alias match and return is best matched address
  • localityName is a phonetic, alias or adjacent neighbour and result is best matched address
  • complexLevelNumber is returned but not provided in input
  • complexLevelNumber is not matched but complexUnitType is matched
94-95% - Good Candidates
95
  • Any condition covered by 96%
  • localityName is a phonetic, alias or adjecent neighbour
  • streetName is a phonetic or alias match
94
  • Any condition covered by 95%
  • Complex information is provided in the input but not returned in the result
91-93% - Possible Candidates
93
  • Any condition covered by 94%
  • A streetSuffix is additionally returned. Alternative streetSuffix for the address exist, however, streetName and localityName match.
  • localityName is an adjacent neighbour and result is not the best matching address.
  • streetNumber2 does not match.
91
  • Any condition covered by 93%
  • streetSuffix does not match
  • complexLevelNumber does not match
71%-90% - Nearby Addresses
90
  • Any condition covered by 91%
  • complexUnitIdentifier does not match
89
  • Any condition covered by 90%
  • streetNumber1 falls within street number range
  • streetNumber2 falls within street number range
87
  • All address where one of:
    • streetName
    • localityName and stateTerritory
    • postcode
    match without using near neighbour, alias or phonetic matching
75
  • stateTerritory does not match
less than 70% - Speculative
less than 70
  • Addresses results lower than 70% are considered a best guess only


NSW Point API Error Codes

NSW Point Predictive Search 1 Web Service

Applies to: address-validation-predictive1 Web Service
Derived from: Geoscape Suggest Addresses Web Service

HTTP Code Error Code Description
400 PPSS-0003 No search terms were provided.
400 PPSS-0006 Excessive number of results to return. Request less than the limit of results.
400 PPSS-0005 Insufficient number of results to return. Request more than zero results.
400 PPSS-0008 This query is too small to return useful results.
401 PPSS-0029 API Key does not grant access to this resource.
401 PPSS-0026 No such API Key was found.
403 PPSS-0041 API Key is inactive.
403 PPSS-0042 Developer is inactive.
403 PPSS-0043 Developer Application is inactive.
403 PPSS-0044 Company is inactive.
403 PPSS-0045 IP is denied access.
403 PPSS-0053 The request quota for this period has been exhausted.
429 PPSS-0051 This service is experiencing heavy traffic. Please slow your requests.
429 PPSS-0052 This service is experiencing sudden heavy traffic. Please retry your request soon.
500 PPSS-0000 An unknown application error occurred.
500 PPSS-0004 An error has occurred with the search engine.
501 PPSS-0054 Version unsupported.
503 PPSS-0002 Search index unavailable.
504 PPSS-0001 Search query timed out.


NSW Point Predictive Search 2 Web Service

Applies to: address-validation-predictive2 Web Service
Derived from: Geoscape Get Address Web Service

HTTP Code Error Code Description
401 PPSS-0029 API Key does not grant access to this resource.
401 PPSS-0026 No such API Key was found.
403 PPSS-0041 API Key is inactive.
403 PPSS-0042 Developer is inactive.
403 PPSS-0043 Developer Application is inactive.
403 PPSS-0044 Company is inactive.
403 PPSS-0045 IP is denied access.
403 PPSS-0053 The request quota for this period has been exhausted.
429 PPSS-0051 This service is experiencing heavy traffic. Please slow your requests.
429 PPSS-0052 This service is experiencing sudden heavy traffic. Please retry your request soon.
500 PPSS-0000 An unknown application error occurred.
501 PPSS-0054 Version unsupported.


NSW Point Parsed and Unparsed Address validation Web Services

Applies to: address-validation-parsed Web Service address-validation-unparsed Web Service
Derived from: Geoscape verifyParsedAddress Web Service Geoscape verifyUnparsedAddress Web Service

Code Message Cause
PS00001 Invalid Username/Password PSF was called with an invalid username/ password combination.
PS01007 Invalid Request: A required feature element is missing from your request. A mandatory feature was not provided and had no default value in the function definition. This can be caused by not specifying a batchAction feature or not supplying a jobID in a getStatus call.
PS01010 Invalid Request: The structure of your request is incorrect: Illegal feature in function declaration: Input request XML had invalid structure of xml or xml tags were not named correctly
PS01012 Invalid Request: A value in your request is invalid. The batch request does not contain a batchAction parameter with the value ‘submit’ or ‘getStatus’.
PS01030 A workflow step has generated an error: (workflowName) (feature-Name) Workflow step generated an error, either it doesn’t exist or NAMF input feature for the NAMF workflow doesn’t exist.
PS01042 The function used for this call does not exist or you do not have access to it. The user does not have the required privileges to execute the specified function.
PS01044 The batch job requested in this call does not exist or has been removed from the system. The jobID supplied in a getStatus call does not exist within the Geoscape Cloud. Either the jobID is the wrong value or the batch job has already been removed from Geoscape Cloud because it has been completed for a set amount of time.
PS01045 The batch jobID returned by the Batch Engine already exists. A Batch Engine has returned a previously used jobID value.
PS01047 The batch server has not returned a jobID attribute on a submit call. The NWS did not return an attribute called jobID in its response to a submit request.
PSMS-VA001 (feature value) is not a valid value for field (feature name) Validation against service metadata failed for a given field
PSMS-VA002 Feature (feature name) is not an integer, as required A feature which expects an integer value has received a non-integer value
PSMS-VA003 Feature (feature name) is mandatory, but was not supplied Validation against service metadata shows that a field marked as mandatory was not supplied
PSMS-VA004 There is no job with ID: (jobID) A non-existent jobID has been passed to a getStatus query
PSMS-VA006 Invalid address fields entered for specified validationType Fields that are required to be populated for a validationType have not been populated
PSMS-DB001 Column does not exist -There was a problem with the search criteria entered. Column does not exist - There was a problem with the database search criteria entered.
PSMS-DB002 There is a configuration error relating to user permissions in the datastore used by the service The user configuration for validateAddress has been set to a user that doesn’t have access to the procedures or tables referenced by the service
PSMS-DB003 An unhandled exception occurred whilst connecting to the datastore used by this service Unhandled exception occurred issuing the query to the database
PSMS-BV001 jobID required when batchAction is ‘getStatus’ A getStatus query has been issued without a corresponding jobID
PSMS-BV002 jobID should not be passed when submitting a new job. Did you want to pass getStatus? A submitJob query has been issued, but a jobId has been passed with it
PSMS-BV010 (feature name) is required when batchMode is CSV, but was not supplied A NAMF Feature with the specified (feature name) is required when batchMode is CSV, but was not supplied
PSMS-BV020 (feature name) is required when batchMode is CSV and batchAction is submit A NAMF Feature with the specified (feature name) is required when batchMode is CSV and batchAction is submit, but was not supplied
PSMS-BV018 Both Primary and Secondary flag can’t be false. Address searched with both primaryFlag and secondaryFlag set to ‘false’
PSMS-AP001 An unhandled application error occurred. This error is displayed when error is not handled in the application
PSMS-PA001 AddressNotParsed: could not parse NAMF application couldn’t parse the address
50000 Invalid username/ password for service. Please try again, or contact service provider if problem persists User entered incorrect username/ password combination to connect to the application.
50000 (requestName) is not a supported function of this server User provided a function name which is not supported by Geoscape Cloud.
50001 An unhandled application error occurred This error is displayed when error is not handled in the application while connecting to the server.
50002 (fieldname) is a mandatory field for this function. It’s a nullReference exception for a mandatory field which was not provided in the input/ request xml.
50004 Feature (Feature Name) was supplied twice. User provided a NAMF feature twice in request xml.


Notes

Note ID Name Priority Value Cause
NOT-1 invalidFeature INFO (feature Name) is not a valid field for this function, and was ignored The service metadata suggests that this field is not supported
NOT-2 addressNotParsed INFO TRUE Address couldn’t be parsed.
NOT-3 addressFound INFO FALSE Address was not found