{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"760a6bf6-44f3-4600-a0a0-e64380141d06","name":"API documentation","description":"# 📄 Overview\n\n---\n\nThe API attempts to conform to the design principles of Representational State Transfer (REST). Methods to retrieve data from the API require a GET request. Methods that submit, change, or destroy data require a POST or PUT. A DELETE request is required for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one. HTTP Response Codes are meaningful.\n\n## **Endpoints**\n\nHTTPS endpoints are available for all APIs.\n\nThe current endpoint for the API is: `https://api.realestate.co.nz/1/`\n\n- You must use a valid API Key to send requests to the API endpoints.\n    \n- The API has rate and usage limits.\n    \n- All request parameter values should be converted to UTF-8 and URL encoded. All request paths should include a trailing `/`.\n    \n\n## Authentication\n\nAll API calls must be signed. Each application/developer will be issued with an API key (public) and an API secret (private). The process of signing is as follows:\n\n1. Make sure any URL request parameters (GET) are UTF-8 & URL encoded.\n    \n2. Sort your URL argument list into alphabetical (ASCII) order based on the parameter name and value.  \n    `e.g. max_results=100, listing_type_id=1, format=full sorts to format=full, listing_type_id=1, max_results=100`\n    \n3. Concatenate the below items into a single string, ensuring it is in lower case:\n    \n    1. your API secret (private)\n        \n    2. the request path, including a trailing slash (eg. /1/listings/)\n        \n    3. sorted URL argument name-value pairs, if any  \n        `e.g. ApiSecret/1/listings/formatfulllisting_type_id1max_results100`\n        \n4. Calculate the MD5 hash of this string  \n    `e.g. &api_sig=20f6224cb85693ecab0297f1c0fc9207`\n    \n5. The final request URL should resemble the below:  \n    `https://api.realestate.co.nz/1/listings/?format=full&listing_type_id=1&max_results=100&api_key=PublicApiKey&api_sig=20f6224cb85693ecab0297f1c0fc9207`\n    \n\n### Authentication error response\n\nIf an API key is missing, malformed, or invalid, you will receive an HTTP 400 response code.\n\n## **Responses**\n\nAll responses will be in JSON format by default. To request a different format pass a HTTP Accept header with the appropriate `content-type` as part of the request. Acceptable content types are: \\* JSON: `application/json`\n\nHTTP Status codes should be used wherever possible to give an overview of the result of the request. In addition, `4xx` or `5xx` responses include a human-readable error description as well, with a response in the following format.\n\n``` json\n{\n  \"success\": false,\n  \"message\": \"Api signature is invalid.\"\n}\n\n ```\n\n## Common Response Codes\n\n- 200 OK - the request completed successfully.\n    \n- 204 No Content - the request completed successfully, and there’s nothing more to say.\n    \n- 400 Bad Request - if one or more parameters are missing or invalid.\n    \n- 401 Not Authorized - the requester is not authorised to access the resource. The API signature does not match the parameters included in the request.\n    \n- 403 Forbidden - the requester is not authorised to access the resource.\n    \n- 404 Not Found - the resource or method wasn’t found.\n    \n- 500 Server Error - there was an error processing the request.\n    \n- 502 Bad Gateway - there was an error processing the request.\n    \n- 504 Gateway Timeout - request timed out.\n    \n\nIf the users passes an `Accept-Encoding=gzip` request header, the response should be gzip encoded appropriately.\n\n## Rate and usage limits\n\nAPI access rate limits apply at a per-API key basis in unit time. The limit is 1000 requests per minute. If you exceed the limit, your request will return an HTTP 502 bad gateway or 504 gateway time out.\n\n### **Need some help?**\n\nOur Platform support team are available via email ([platform@realstate.co.nz](https://mailto:platform@realstate.co.nz)) or Slack. Contact via email if your company doesn't have a support Slack channel yet.\n\n# Images\n\nImages are returned as an md5 image ID:\n\n``` json\n\"images_md5\": [\n  \"dc2cb56eeff397fdc9a616321372ed06\",\n  \"22ab49c3c313124775e632f4cc8d463c\",\n  \"bba32d9a0baac02b22fd99bfadfd50c1\"\n],\n\"image\": \"59de79cc8f197e48cfe2ae05108e74b2\",\n\n ```\n\nTo generate the correct URL for the image concatenate the host, object type, image md5, transformations and image type:\n\n``` json\nhttps://images16.realestate.co.nz///...jpg\nhttps://images16.realestate.co.nz///.jpg\n\n ```\n\n- `https://images16.realestate.co.nz/` is the production image server.\n    \n- use `listings` for listing images and `per_orgs` for agent and office logos.\n    \n- the ID of the listing/agent/office\n    \n- the MD5 of the image\n    \n- the resize mode:\n    \n    - `scale`\n        \n    - `crop`\n        \n    - `auto`\n        \n- the image size. Required size arguments depend on resize mode.\n    \n    - `100x100` specifying width & height\n        \n    - `x100` specifying only height\n        \n    - `100x` specifying only width\n        \n\nNote:\n\nFor Example:\n\n- `https://images16.realestate.co.nz/listings/181319/dc2cb56eeff397fdc9a616321372ed06.scale.400x.jpg`\n    \n\n- `https://images16.realestate.co.nz/per_orgs/17432/cd47f7bc6527cec7e1d884227484cef6.scale.400x.jpg`\n    \n\n# Regions - GET /regions/\n\nReturns a list of available regions. The response should only return enabled & non-Confidential regions.\n\n## Request\n\nNo parameters\n\n## Response\n\n``` json\n[\n {\n  id: 89,\n  name: \"Auckland\",\n  slug: \"auckland\",\n  bounds: null\n },\n ...\n]\n\n ```\n\n# Districts - GET /districts/\n\nReturns a list of available districts and the id of the region it belongs to. The response should only return enabled & non-Confidential districts.\n\n## Request\n\nNo parameters\n\n## Response\n\n``` json\n[\n {\n  id: 678,\n  name: \"Auckland City\",\n  slug: \"auckland-city\",\n  region_id: 89\n  bounds: null\n },\n ...\n]\n\n ```\n\n# Suburbs - GET /suburbs/\n\nReturns a list of available suburbs and the id's of the district/region it belongs to, also returns the id's of nearby suburbs. The response should only return enabled & non-Confidential suburbs.\n\n## Request\n\nNo parameters\n\n## Response\n\n``` json\n[\n  {\n    \"id\": 34567,\n      \"name\": \"Balmoral\",\n      \"slug\": \"balmoral\",\n      \"district_id\": 678,\n      \"region_id\": 89,\n      \"bounds\": null,\n      \"nearby_suburbs\": [1234,5678]\n  },\n ...\n]\n\n ```\n\n| Field | Description |\n| --- | --- |\n| Region Name | Region the suburb belongs to. |\n| District Name | District the suburb belongs to. |\n| Base Suburb Name | The actual suburb/locality. |\n| API Surburb ID | The API suburb ID |\n| FTP SDN | The FTP suburb ID (Deprecated) |\n| Displayed As | The suburb that appears on the site. |\n| Is Deprecated? | Deprecated suburbs will be removed from the list at a later date. Only non-deprecated suburbs can be used with the API |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"7106971","team":24990,"collectionId":"760a6bf6-44f3-4600-a0a0-e64380141d06","publishedId":"2sAXxY48ii","public":true,"publicUrl":"https://docs.api.realestate.co.nz","privateUrl":"https://go.postman.co/documentation/7106971-760a6bf6-44f3-4600-a0a0-e64380141d06","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.0","publishDate":"2024-10-21T21:38:59.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/b2a109a7d7ac7f36c8984e0f3d9471879b762c729da978a61575fc6ffa1afb46","favicon":"https://realestate.co.nz/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.api.realestate.co.nz/view/metadata/2sAXxY48ii"}