api.landsofamerica.comLands of America - LandsofAmerica REST API

Lands of America REST API The Lands of America REST API is designed to give outside parties access to the Lands of America 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 LOA 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 LandsofAmerica 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 CallApiT(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.DeserializeObjectT(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 API Support Team at api-support@landsofamerica.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...