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

{
	"success": true|false,
	"errors": [],
	"data": return value, may be string, struct, or array.
}