|
Rentometer API 2.0
Inbound API Web Service
The Inbound API web service provides a comprehensive suite of resources for creating and managing listings on the Rentometer. All Inbound API requests are made as HTTP post requests using a URL with an XML data payload. The data payload must contain a valid Inbound Rentometer API Key. All responses contain a HTTP status code and XML data payload. Inbound requests may be conveniently made using a number of commonly available tools, including cURL.
For example using the linux curl command, a request may look like:
curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d @data_payload
http://inbound.rentometer.com/ws/real_estates/post
where
@data_payload
points to a file containing XML, with a description of a rental listing and an API key (and request should be a single line); for example (white space added for clarity):
<request>
<token>[Inbound API Key]</token>
<real_estate>
<external_id>1234</external_id>
<image_url>http://yourdomain.com/image.jpg</image_url>
<rent_amount>1500</rent_amount>
<beds>3</beds>
<street_address>248 3rd Street</street_address>
<city>Oakland</city>
<state>CA</state>
<country>US</country>
<building_type>2</building_type>
<expire_on>2007-06-08</expire_on>
<dogs_allowed>1</dogs_allowed>
</real_estate>
</request>
The functionality of the Inbound Rentometer API 2.0 is significantly different from pervious versions and is not backward compatible. However, active rental listings created by previous releases of the API are compatible with the current release.
All responses include an HTTP status code, one of:
200 OK 400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server error
and will include a data payload of MIME type text/xml or application/xml. The Inbound API supports four basic resources ( post, find, list, and remove) along with a "sandbox". Users must use the sandbox when developing new client applications.
The typical request/response process is as follows:
1. Inbound API client submits a request.
2. The request is received by the server and processed.
3. Unless the token is present and valid, a UNAUTHORIZED response is sent.
4. The remaining parameters in the request are validated.
If they are invalid, a BAD_REQUEST response is sent.
Validation is resource specific.
5. A resource specific action is undertaken.
This action may involve additional steps that ultimately generate a BAD_REQUEST response.
For example, geocoding of the location may be attempted.
If geocoding is unsuccessful, a BAD_REQUEST response is returned.
6. The response is sent with a SUCCESS status code, including a data payload
Request Data Payload
The request data payload must be in XML. The entire data payload must be url-encoded. The minimal valid data payload for authentication contains a root <request> node with a single <token> attribute node:
<request>
<token>[Inbound API Key]</token>
</request>
Most data payloads will also contain rental listing objects in a <real_estate> tag.
<request>
<token>[Inbound API Key]</token>
<real_estate>
...
</real_estate>
</request>
where the ellipses signify a set of listing attributes as described below. Request can also contain:
<verbose>true</verbose>
either inside or outside of the <real_estate> object. Use the <verbose> tag to return detailed error messages.
Rental Listings
Specifying Rental Listing using the <real_estate> object will generally require a number of attributes. It is important to note that only one listing may be present for each value of <external_id> . That is, <external_id> must be a unique identifier supplied by the client application. If it is not provided, it is given the value of 0. Valid XML attributes (node / tag names) for the <real_estate> object are listed below. Some combination of the "location" information is required for geocoding and all listings must successfully "geocode" in order to be valid. Unless otherwise listed, all attributes are optional.
<external_id> required OR assumed to be 0; integer >=0 (up to 2^31 - 1)
<description> limited to 100 characters
<rent_amount> required, must be > 0. Do not include currency symbol, etc.
<beds> required, integer, 0 (studio) - 8
<baths> fractional values accepted
<building_type> apartments in bldg, use: x , x-y , or x+
where x & y are integers, x < y and x,y <= 999 (ex: '1-10'),
7 chars max
<dogs_allowed> integer, number of 'dogs' or larger pets allowed, 0 = none allowed,
leave blank for unknown
<street_address> limited to 100 chars., may be altered by geocoding
<city> limited to 50 chars., may be altered by geocoding
<state> limited to 50 chars., may be altered by geocoding,
use 2 chars ("MA") for US
<zip> limited to 15 chars., may be altered by geocoding,
use 5 digit ZIP or ZIP+4 for US
<country> 2 chars; use ISO 3166-1-alpha-2 code, defaults to "US"
[currently must be one of "US", "CA", "GB"]
<date_available> date, use YYYY-MM-DD
<published_on> date, use YYYY-MM-DD
<expire_on> date, use YYYY-MM-DD [defaults to 90 days from creation date]
<url> limited to 100 characters, include protocol
<image_url> limited to 100 characters, include protocol
<revision> integer >=0 (up to 2^31 - 1)
<verbose> use 'true' for verbose error reporting
Response Data Payload
All successful requests return HTTP 200 OK response code. Other response codes indicate a failed request.
The response data payload is in xml. It will contain either a single Rental Listing (with or without error messages), or an array of Rental Listings (without error messages), or an error response. Error messages will only appear if <verbose> is set. Client applications should use the HTTP status code to determine the outcome of a request before attempting to parse returned XML.
For example, the following response contains a single Rental Listing (that echoes back the request) and an array of errors. The API key (<token>) is never returned.
The HTTP status codes for this will be either 200 OK (no errors) or 400 Bad Request (with errors):
<real_estate id="12345">
<image_url>http://yourdomain.com/image.jpg</image_url>
<city>Springfield</city>
<external_id>1234</external_id>
....
<state>AK</state>
<error number="0">error text</error>
<error number="1">error text</error>
</real_estate>
The following example response contains an array of Rental Listings. Again, the API key (<token>) is never returned. The HTTP status code for this kind of response (with an array of rental listings) will always be 200 OK .
<real_estates>
<real_estate id="12345">
<image_url>http://yourdomain.com/image.jpg</image_url>
<city>Springfield</city>
<external_id>1234</external_id>
....
<state>OH</state>
</real_estate>
<real_estate id="67890">
<city>Springfield</city>
<external_id>1235</external_id>
....
<state>VA</state>
</real_estate>
</real_estates>
Certain other operation may return the following with a status code of 200 OK (such as remove)
<response success="true"/>
And finally, the following shows an error response. The status codes for this will be 404 Not Found:
<response success="false">
<error code="404" kind="ActiveRecord::RecordNotFound">
Couldn't find RealEstate with ID=99
</error>
</response>
Failure to provide a valid token will results in an 401 Unauthorized error response:
<response success="false">
<error code="401" kind="401 Unauthorized">
You must specify a valid API token.
</error>
</response>
Resources
Post: Create or Update a Rentometer Listing
Use the post resource to create new or update existing Rentometer listings. Request must contain a valid Inbound API Key and a valid Rental Listing. New listings are created by specifying a new value of <external_id>. If the value of <external_id> is already in the system, the listing with that value of external id will be updated (if the update is valid). For new listings, enough information must be provided in the request to successfully geocode. For updates, the combination of the existing location information and new data supplied in the request (if any) must be sufficient for successful geocoding.
Resource URLs:
/ws/real_estates/post
/ws/sandbox/real_estates/post
Required request data payload:
minimal data payload + valid real estate listing object
Response:
a single real estate listing (echo of request + update from geocoding)
Errors:
invalid / missing token : 401 Unauthorized
invalid real estate object: 400 Bad Request
Remove: Delete a Rentometer Listing
Use the remove resource to delete an existing listing from the Rentometer. Request must contain a valid Inbound API Key. Listing to delete is specified by its <external_id> (within the <real_estate> object).
Resource URLs:
/ws/real_estates/remove /ws/sandbox/real_estates/remove
Required request data payload:
minimal data payload + real estate listing object with <external_id>
Response:
<response success="true"/>
Errors:
invalid / missing token : 401 Unauthorized
invalid <external_id> : 404 Not Found
Find: Returns a Rentometer Listing
Use the find resource to locate and return an existing listing from the Rentometer. The request must contain a valid Inbound API Key. The listing to find is specified by its <external_id> (within the <real_estate> object).
Resource URLs:
/ws/real_estates/find /ws/sandbox/real_estates/find
Required request data payload:
minimal data payload + real estate listing object with <external_id>
Response:
a single Rental Listing
Errors:
invalid / missing token : 401 Unauthorized
invalid <external_id> : 404 Not Found
List: Locate and return all Rentometer Listings for client
Use the list resource to locate and return all existing listings for a particular Inbound API Key. Request must contain a valid Inbound API Key. The list resource returns only the first 100 Rentometer LIstings for an individual Inbound API Key.
Resource URLs:
/ws/real_estates/list /ws/sandbox/real_estates/list
Required request data payload:
minimal data payload
Response:
an array of Rental Listing, containing 0, 1, or more <real_estate> objects.
Errors:
invalid / missing token : 401 Unauthorized
invalid <external_id> : 404 Not Found
Best Practices
Developers must use the "sandbox" resources until correct operation of client application can be demonstrated. Development on the main resource (non "sandbox") is prohibited and abuse will result in deactivation of the user's Inbound API Key.
The Inbound API is web based synchronous service and client applications should use an appropriate time-out to handle long running requests during periods of high API usage. Since listings are referred to using a unique identifier provided by the client application (<external_id>), clients can inquire about the state of a listing (and therefore the effects of any request) at a later time and need not receive a synchronous response during the timeout period). Client applications should limit their use of update requests by utilizing the find resource and to return revision information (via the <revision> code). For example, client applications can determine if an update request was successful (after a timeout) by comparing the value of <revision> for the updated listing to the value for the non-updated listing. Client applications can also look at the value of <updated_at>, which will reflect the time the updated was committed (if it was committed). The use of the <revision> code is somewhat preferred to monitoring <updated_at> since the Inbound API may need to alter the listing for maintenance (though this is unlikely).
Rentometer Listings created using the Inbound API will be used by the Rentometer Web Application and the information will be publicly viewable (please see the terms of use for more information).