The Land.com Network REST API is designed to give outside parties access to the Land.com Network listings and search applications.
The current version of the API is 3.0.1. You can view documentation and the API dashboard at https://api.landsofamerica.com/v3/.
Version 2: https://api.landsofamerica.com/v2/ (deprecated, support ends December 1st, 2017)
All API URLs listed in this documentation are relative to
https://api.landsofamerica.com/
. For example, the
/v3/locations/states
API call is reachable at
https://api.landsofamerica.com/v3/locations/states
.
The latest release notes can be found at the bottom of this document. You can also subscribe to our RSS feed detailing changes made to the API.
The Land.com Network API does its best to follow RESTful conventions. View the description of each resource to determine if there are changes in default REST behavior for a particular resource.
Access to the Land.com Network REST API is via SSL only. All requests must be through the HTTPS protocol, and must not
use weak ciphers. Client requests should use TLS 1.2 or higher, as any SSLv2 or SSLv3 requests will be rejected at the firewall. Below is a sample WebClient
call from .NET using TLS 1.2 with the relevant lines highlighted.
T CallApi<T>(NameValueCollection parameters, string url) where T : new() { //Merge the parameters and the URL url = url + "&" + HttpUtility.UrlEncode(parameters.ToString()); ServicePointManager.Expect100Continue = true; ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; ServicePointManager.ServerCertificateValidationCallback = delegate { return true; }; using (var wc = new WebClient()) { try { var data = wc.DownloadString(url); return !string.IsNullOrEmpty(data) ? JsonConvert.DeserializeObject<T>(data) : new T(); } catch (Exception ex) { _ErrorService.LogException(ex); return new T(); } } }
Request data is passed to the API by sending GET or POST requests to the API endpoints with the appropriate parameters. The documentation for each API call will contain more detail on the parameters accepted by the call.
All requests to the API must include an API Key in the URL of the request. The API Key is unique per user, and should not be published publicly. You will provide the API Key in the URL of each request using the following format:
https://api.landsofamerica.com/v3/locations/states/?APIKey=[Example Key]
All additional resource parameters can be placed anywhere within the query. The order of the passed parameters is not important.
https://api.landsofamerica.com/v3/listings/1234/?APIKey=[Example Key]&includeImages=true
or
https://api.landsofamerica.com/v3/listings/1234/?includeImages=true&APIKey=[Example Key]
In order to prevent abuse of the API, rate limits will be strictly enforced. We will, however, work with you to ensure that you are allowed a reasonable rate of requests in order to serve your audience appropriately. Each request made to the API will return information on the current state of your rate limit. The following header values will be returned with each request:
Here is an example of headers returned with a request:
x-ratelimit-limit:60; x-ratelimit-remaining:35; x-ratelimit-reset:1409212860; x-ratelimit-seconds-remaining:33;
This particular user is allowed 60 requests per minute. They've used 25 of their requests and have 33 seconds remaining before their rate limit is reset.
Access to the API will be restricted by IP address. You will be able to add new IP addresses through the PropertyControlCenter in order to ensure that all relevant servers within your organization have access to the API.
For GET requests, any status other than 200 OK
or
201 Created
can be considered an error. If a value other
than 200 OK
or 201 Created
is returned, the body
of the request will also contain a list of errors that happened during the
request. There will generally be only one error, but in the case of
validation errors for inputs there may be multiple errors if there are
mutliple inputs with invalid data. Below are several examples of errors that
may be returned.
/v3/types/{type}
with an invalid type400 Bad Request
{ "success": false, "data": "" "errors": [ "Invalid Type: No valid type provided" ] }
429 Too Many Requests
{ "success": false, "data": "" "errors": [ "Rate Limit Exceeded: You have exceeded the rate limit." ] }
The following headers would also be returned:
x-ratelimit-limit:60 x-ratelimit-remaining:0 x-ratelimit-reset:1409213340 x-ratelimit-seconds-remaining:11
/v3/listings/1234
where ID 1234 does not exist.404 Not Found
{ "success": false, "data": "", "errors": [ "Invalid Listing ID: The listing id provided could not be found." ] }
/v3/lead
with multiple validation errors400 Bad Request
{ "success": false, "data": "", "errors": [ "Contact name missing: The value for contact name was not provided", "Email address missing: The value for Email address was not provided", "Phone number missing: The value for Phone number was not provided", "Comment missing: The value for comment was not provided", "Invalid listing ID: The listing ID provided could not be found" ] }
If there are issues directly related to the use the API, you can contact our Support Team at support@land.com. Response times are not guaranteed, but we will try to respond to all reasonable requests within 24 hours.
Lots of adjustments to standardize the API return values, and add additional internal methods not available to the public.
Type | Change |
---|---|
New Feature | Standardized all return values to the following format for both success and errors:{ "success": true|false, "errors": [], "data": return value, may be string, struct, or array. } |
Internal API customers may now elect not to send an email notification when posting a lead by providing false
for the sendNotification
argument. External API customers may provide the sendNotification
argument, but it will be ignored.
Type | Change |
---|---|
New Feature | Added optional sendNotification argument to the lead resource. |
In Version 2, property types were completely reworked. New property types have been added, and the manner in which types are passed to the API have been changed.
To use Version 2 of the API, you must adjust all URLs to use the v2
directory after the URL, i.e. https://api.landsofamerica.com/v2/
.
Check the API document for the types
, listings
, showcaselisting
, and listing
resources to review the changes.
Type | Change |
---|---|
New Feature | Adjusted property types to support new and expanded property type values in Version 2.0 |
New Feature | Update to types resource. |
New Feature | Update to listings resource. |
New Feature | Update to listing resource. |
New Feature | Update to showcaselisting resource. Return values match the changes discussed for the listing resource. |
Added bounds
and includeBoundaries
arguments to the listings
resource.
Type | Change |
---|---|
New Feature | The listings resource now allows for a boundary to be provided via the bounds argument. The argument takes a standard map bounding box in Google's default format. The format is (SWlat,SWlng),(NElat,NElng) . You provide the lower left and upper right corner of the boundary you'd like to search within, and we'll return results within that bounding box. |
New Feature | The listings resource will now return the property boundaries for a listing when the includeBoundaries argument is set to true . The boundaries will be provided in the encodedPolyline node of the returned JSON structure, and will be in Google's Encoded Polyline Algorithm Format. |
Added showcase
and showcaselisting
resources.
Type | Change |
---|---|
New Feature | The showcase resource allows for the retrieval of a random list of Showcase properties related to the API account making the request. Listing URLs from this resource point to the new showcaselisting resource. |
New Feature | The new showcaselisting is a super class of the listing resource. The only difference being that it logs the fact that a Showcase property was viewed via the API. When displaying listing details from a Showcase listing click, ensure you use this more specific resource. This ensures that customers purchasing your Showcase properties know how well their listings are performing. |
Added lastModified
key to listings
resource.
Type | Change |
---|---|
New Feature | The listings resource now includes a lastModified key for each listing in the results. Use this value to determine the last time a listing was changed. |
Official release of Version 1 of the LandsofAmerica REST API.
Type | Change |
---|---|
New Feature | You can now add custom request headers from the dashboard in order to more accurately emulate requests from your server. |
New Feature | JSON responses will now have syntax highighting when displayed in the dashboard results area. |
Bug | Corretly URL Decode strings to prevent "some string" from turning into "some+string" . |
Type | Change |
---|---|
New Feature | Add filtering to the listings and listing resource to limit display of listings to only those associated with a specific partner. |
New Feature | Adjust lead resource to ensure that partners are properly mentioned in lead notification emails. |
Bug | Adjusted lead resource to allow for invalid values to be POSTed, and return custom error messages. Previous behavior returned a stack exception if a value was missing. |
Type | Change |
---|---|
New Feature | Added listingTitle attribute to the return values for listings and listing . |
New Feature | Added includeDescription option to listings to allow for a short description to be returned in search results. Returned in the description element for each listing returned. |
New Feature | Added largerThumbnails option to listings to allow for larger thumbnails to be returned in search results. |
This is the initial Alpha release of the API.
Type | Change |
---|---|
Bug | Corrected the 401 response to ensure it returns the status text "Access Denied". |
Bug | Corrected the listings and agent URL examples on the listing resource. |
Bug | Corrected the listing_URL value returned from the listings resource. |
Documentation | Formatting changes to header definitions in documentation. |
Documentation | Added notes for Google's Encoded Polyline algorithm on the listing resource. |
Documentation | Added the maximum allowed content length to the lead resource's comment value. |
Documentation | Corrected the sample return format for the regionCounties resource.. |