This section provides some links to external technical resources related to SAPI.
HTTP 1.1 (Hypertext Transfer Protocol)
The protocol used for sending and receiving API messages is HTTP Version 1.1. Basic knowledge of this protocol is recommended. However, depending on the programming language and tools being used, an in-depth understanding of HTTP may not be required.
- HTTP 1.1 Specification
- HTTP Status Codes
- W3C Protocols Page (more information and specification updates)
URLs (Uniform Resource Locators)
URLs are used (in conjunction with HTTP) to specify the location of the SAPI server, the type of search and the search parameters. A thorough understanding of URLs is recommended, specifically the encoding of prohibited characters.
JSON is a lightweight data-interchange format used in all SAPI response messages. The actual listings are returned in JSON format, as well as status codes and messages. Familiarity with JSON is essential. However, depending on the programming language and tools being used, an in-depth understanding may not be required.
- JSON website (specification, other resources and libraries)
Web Browsers and JSON
All you need to try out the API is a good web browser. The API is based on HTTP GET requests, and returns human-readable JSON responses. However, not all browsers handle the JSON responses very well.
Some browsers will happily display the JSON text, while others will prompt you to download the response as a file. If your browser does prompt you to download a file, simply open it up with a text editor such as Notepad for viewing. Some older browsers may simply refuse to render or download the response at all.
We recommend you use one of the following browsers for testing out the API:
Note: The fact that certain browsers cannot handle JSON will have no effect on what browsers can be used to view your website. JSON is only used as the protocol between SAPI and your application. What happens beyond that is completely within your control.
Viewing JSON as text can sometimes be hard to read. To make the JSON even more readable you can use a JSON formatter plug-in. There is plug-in called JSONView that formats JSON response messages using colour and indenting. Unfortunately it is currently only supported in Mozilla Firefox.
HTTP Client Library
In order to send API requests, you will need to be able to communicate with the API endpoints using HTTP. The library you use depends on the type of website or application, and the programming language being used.
- For Java, see the HttpURLConnection class or the Apache HttpClient library.
- For PHP, see the HttpRequest class.
- For Ruby, see the Net::HTTP object.
For other programming languages please, consult the language documentation.
See also: Code Examples
The response messages returned by the API are encoded in JSON. Depending on the programming language or framework you are using, you will probably need a JSON parser. An extensive list of JSON libraries can be found on the JSON website.
- For Java, see the Jackson JSON Parser library.
- For PHP, see the json_decode() function.
- For Ruby, see the JSON implementation for Ruby library.
For other programming languages, please consult the language documentation.
See also: Code Examples
- Documentation Overview
- Getting Started
- Using Endpoints
- Common Fields
- Status Codes and Messages
- Validation Errors
- Spell Checker
- Search Query Tips
- Reporting Usage Events
- Filtering Unsafe Content
- Category Filtering
- Postcode Filtering
- Radius Filtering
- Address Search
- Suburb Filtering
- State Filtering
- Bounding Box Filtering
- Filtering by Content Type
- Filtering by Product Keyword
- Location Tier Filtering
- Filtering by Polygon
- Endpoint Reference