Developer's Guide

---

Introduction
Prerequisites
API Methods
API Endpoints
API Configuration
API Input
API Output
Error Codes
Test your API
Download Developer's Guide

---

Introduction
SGLocate from SingPost offers postal address search based on postcode, street and block with simple API calls. Our API can give you a qualified postal address with postcode, block number, building name, and street name. The enhanced versions of API can also provide building details such as building code and description, latitude and longitude of the post code, floors and units inside the postcode (additional charges may apply).

Prerequisites
Before configuring the API you may have a valid SGLocate account and a product subscription. In addition you may need to have little bit of experience on how API systems works and knowledge in SOAP based web service, XML or JSON technologies to interface with the API.

API Methods
The API supports two methods and are:

• SearchByPostcode(): Provide a postcode and get the address record
• SearchByBlockAndStreetName(): Provide block, street or the combination of block or street to get the address record

We support the the following technologies to access the API. To know more about the different technologies please have a look at the last section “API access technologies”

• SOAP
• HTTPS (XML or JSON outputs)

API Endpoints
SOAP endpoints
Service URL: https://www.sglocate.com/api/service.asmx
WSDL URL: https://www.sglocate.com/api/service.asmx?WSDL

HTTP Post - XML output format
Search with postcode: https://www.sglocate.com/api/xml/searchwithpostcode.aspx
Search with block or street: https://www.sglocate.com/api/xml/searchwithblocknumberandstreetname.aspx

HTTP Post - JSON output format
Search with postcode: https://www.sglocate.com/api/json/searchwithpostcode.aspx
Search with block or street: https://www.sglocate.com/api/json/searchwithblocknumberandstreetname.aspx

API Configuration
You may need to add your domain API configuration to your account before you call the API. In addition to this for each API you can whitelist the IP range so that you can ensure that no one else expect your authorized servers are calling the API without your permission even if you lose the API details. However this is an optional setting.

• Login to your account via: www.sglocate.com
• On the main menu select “My Account ➤ My Subscription”
• If you have a valid subscription it will be listed here. As a default you will be able to see the demo plan ready for testing. However please note demo plan will allow you to search only a specified set of postal codes or block number and street name combinations. To see a full list of allowed items for demo plan, please click here.
• To add your API groups please on the link “+ Add a new API group”.
• On new domain configuration page, please provide your API group name. API group name is just for your easy reference. Once added you will get the API key and secret. If you wish, you can add an IP whitelist so that you can make sure that only the API calls are made from your servers even if you lost the API key and secret.
• You are now ready to do the API calls with various methods. For the API endpoints please refer the previous section “API endpoints”.

API Input
Please note you must URL encode all your parameters to make sure the API call is a fully qualified XML request.

• Must have parameters: APIKey and APISecret are the two must have parameters to call any API methods. This will identify and validate your API call with us.
• Search by postcode: This method needs the parameter Postcode as a search team. You must provide a postcode with 6 characters. Please note postcode search will take only valid postcodes and no like search is allowed.
• Search by block and street name: This methods needs parameters Block and StreetName. You may need to provide at least 1 character for the block name and 3 characters for street name.

API Output
Once an API method is called you will get an XML or JSON output (based on your call type) named APIResponse:

The main components of the objects are the output status indicators such as IsSuccess, ErrorCode, and ErrorDetails in addition with the result postcode record array named Postcodes. IsSuccess will give you a true or false indication to quickly understand whether your API call is a success or failure. The error code and error details will explain in detailed if the call is not succeeded. You may get more details on the error code at the next section “Error codes”.

Depends on your search you may get one ore more Postcode6D object in your Postcodes array. For example, you may get multiple records with matching postcodes (maximum 50 records). Each Postcode6D object contains the following elements for further exploration.

Elements in PostCode6D object

• Postcode
• BuilidngNumber
• StreetName
• BuildingName

Additional Elements
(These elements will be filled based on your subscription plan) If subscribed to building details

• BuildingCode
• BuildingDescripton

If subscribed to Lat-Long of the postcode

• Longitude
• Latitude

If subscribed to Floor and Unit

• Each postcode will be will with an array Floors that contains each Floor in the building as FloorNumber
• Each Floor object will contains the Units array that contains Unit in the floor as UnitNumbres

A sample Postcode6D object is given as a sample below (XML output):



Error Codes
Error codes will help you to understand and customize various failure scenarios. The list of error codes that can be obtained from the system is given below:

ERROR CODE	ERROR DETAILS
1	The API call is a success and it's with results. This is the only case you receive “IsSuccess” flag as true. All other cases "IsSuccess" flag will be false and you will get an -ve value in error code.
-1	System is too busy to process your request, please try again later This might be the rarest error in the system and you will not get this in usual cases. If you ever get this message, please contact us.
-2	System is under maintenance, please try again after few moments. Monthly rollover window for postcode refresh. The automated rollover for about 2 million postal address take about 3 to 5 min in each month and the rollover window will be pre-announced. The regular schedule for the rollover is 3rd of every month at 6:00PM.
-3	You must provide at least 6 characters for the postcode. If the method used to call API search is SearchbyPostcode() and you provided less number of characters to search.
-4	You must provide at least 1 characters of the block or 3 characters for street name. If the method used to call API search is SerachbyBlockAndStreetName() and you provided less number of characters to search.
-5	You must provide at least 3 characters of the building name. If the method used to call API search is SearchByBuildingName() and you provided less number of characters to search.
-6	Unable to find the API details you have provided. If the API credentials are invalid.
-7	The user account is not yet activated. A valid API details exists but the user account is not yet activated.
-8	The user account is suspended. A valid API details exists but the user account is disabled by the SGLocate administrator.
-9	An IP whitelist is configured with this API settings and we are receiving an unauthorized IP: [Received IP] If the domain configuration is wrong, customer must configure their calling IP address correctly against the API details in their account. This will happen only if you choose to use IP or IP range validation for your domain.
-10	The subscription is not yet approved by the SGLocate administrator. The API detail for the subscription exists but it's not yet approved. If it's an online payment this case will not appear.
-11	The subscription is suspended by the SGLocate administrator. The subscription against the current received API details are suspended by the administrator.
-12	The subscription is marked for future use. The details are valid but the subscription is not yet started and marked for a future date.
-13	The subscription is expired. The subscription is not renewed or no auto renewal is worked.
-14	Additional usage limit is reached. The additional usage limit for the current subscription is reached. You may increase it from the subscription details page by logging in to your account.
-15	No valid results for your request. This will be considered as a valid API call even if there is no results are obtained.
-21	Unauthorized postcode for demo plan If you are testing the API with a demo plan then only a list of postcodes published in our side will be allowed.
-22	Unauthorized block and street name for demo plan If you are testing the API with a demo plan then only a list of block and street name combinations published in our side will be allowed.

Test your API
Once configured you may simply test your API with the following HTTPS post XML method. Just make sure you have given correct APIKey and APIScret in your form that you get from the website under your account. To test this, copy the code and save it as an HTML file. Open it in a browser and click on the submit button. To test JSON method just change the /xml/ in the form action to /json/. If you wish to test with SOAP method please refer the URL https://www.sglocate.com/api/service.asmx.
<form action="https://www.sglocate.com/api/xml/searchwithpostcode.aspx" method="post"> <br> <br/> <h3>Sample HTML Post API for XML output</h3> <br> API Key: <br/> <input type="text" name="APIKey" value="Your API key here..."> <br> <br/> API Secret: <br> <input type="text" name="APISecret" value="Your API secret here..."> <br> <br/> Postcode: <br> <input type="text" name="Postcode" value="408600"> <br> <br> <input type="submit" value="Post"> </form>

Download Developer's Guide
Please click here to download developer's guide in pdf format.