Land.com Network REST API

The Land.com Network REST API is designed to give outside parties access to the Land.com Network listings and search applications.

Current Version

The current version of the API is 3.0.1. You can view documentation and the API dashboard at https://api.landsofamerica.com/v3/.

Previous Versions

Version 2: https://api.landsofamerica.com/v2/ (deprecated, support ends December 1st, 2017)

API Endpoint

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.

Release Notes

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.

RESTful

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.

SSL-Only Access

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();
                }
            }
        }

Passing Request Data

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.

Authentication

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]
		

Rate Limiting

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:

x-ratelimit-limit
The number of requests allowed per minute for your API Key
x-ratelimit-remaining
The number of remaining requests in the current time range
x-ratelimit-reset
An epoch time representation of when your rate will reset back to the maximum value
x-ratelimit-seconds-remaining
The number of seconds before your rate limit will be reset

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.

IP Restrictions

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.

Error Handling

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.

Request to /v3/types/{type} with an invalid type

400 Bad Request

{
   "success": false,
   "data": ""
   "errors": [
      "Invalid Type: No valid type provided"
   ]
}

After sending too many requests and exceeding the rate limit

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
		

Request to /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."
   ]
}

POST to /v3/lead with multiple validation errors

400 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"
   ]
}

API Support

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.

Release Notes

Version 3.0.0 - Pre-release

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.
}

Version 2.0.1 - June 3, 2016

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.

Version 2.0.0 - May 31, 2016

Breaking Change

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.

Version 1.1.0 - 9 February, 2016

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.

Version 1.0.2 - 15 July 2015

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.

Version 1.0.1 - 27 January 2015

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.

Version 1 - 19 November, 2014

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".

Version 0.7 - 14 November 2014

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.

Version 0.6 - 16 October 2014

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.

Version 0.5 - 28 August 2014

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..