Rentometer API 2.0

Outbound API Web Service

The Outbound API web service is limited to performing Rental Data Search through a single HTPP resource and a simple query. For example, the following will retrieve Rental Statistics (in XML format) for 2 bedroom apartments in the US 02115 ZIP code:

  
  http://out.rentometer.com/ws/query?token=[API Key]&citystatezip=02115&rent=2800&beds=2
  

Note: [API Key] should be replaced with a valid Outbound API Key. 

The search function handles a range of query parameters, many of which are optional, as described below.

Search Results

Outbound API Search Results are returned in 3 formats; XML, JSON, and PNG.  Successful XML and JSON request results may contain Query information, Rental Statistics and optionally comparable Rental Listings and a "link" to a similar Rentometer Web Application search. PNG formatted results contain an image.  Bad Requests and Unauthorized access will result in error responses.

XML Requests

Valid XML requests return a "200" status code and XML in the following format, for the above sample request (whitespace added for clarity). When there is insufficient data available to compute statistics (and the request is otherwise valid) values for the rental statistics will be omitted and comps will not be returned. The returned address tag contains the full address and additional information from geocoding is included when available.

  
  <!-- Rentometer Outbound API ver 2.0 -->
  <rentometer>
  <address>Boston, MA 02115</address>
    <rent>$2,800</rent>
    <beds>2</beds>
    <bt/>
    <city>Boston</city>
    <state>MA</state>
    <zip>02115</zip>
    <country>US</country>
    <longitude>-71.09286</longitude>
    <latitude>42.340411</latitude>
    <low_rent>$550</low_rent>
    <median_rent>$2,400</median_rent>
    <high_rent>$5,200</high_rent>
    <entered>2008-08-31T16:06:57Z</entered>
    <generator>http://www.rentometer.com</generator>
    <link>http://www.rentometer.com/?show=results&beds=2&citystatezip=02...</link>
    <comps>
        <comp>
            <rent>$2,000</rent_amount>
            <latitude>42.33918</latitude>
            <longitude>-71.09223</longitude>
            <distance>0.09 (miles)</distance>
        </comp>
        <comp>
            <rent>$1,895</rent_amount>
            <latitude>42.33884</latitude>
            <longitude>-71.09248</longitude>
            <distance>0.11 (miles)</distance>
        </comp>
        ...
        ...
    </comps>
  </rentometer>
  

Invalid Requests Examples (assuming verbose query parameter is used; HTTP status codes are set appropriately). Note that returned address here is from the request.

  
  <response success="false">
    <error code="401" kind="401 Unauthorized">
  ApiUser with token=Invalid_Token could not be found
    </error>
  </response>
  

  
  <!-- Rentometer Outbound API ver 2.0 -->
  <rentometer>
    <address/>
    <rent>$-1,000</rent>
    <beds>44</beds>
    <bt/>
    <citystatezip>00000</citystatezip>
    <city/>
    <country>US</country>
    <error id="0">Please check the zipcode.</error>
    <error id="1"> Please specify a valid positive number as your monthly rent. </error>
    <error id="2">Please specify between 0 and 8 bedrooms.</error>
  </rentometer>
  

If the Outbound API is unable to geocode (find) your location, it will return an error like:

  
  <!-- Rentometer Outbound API ver 2.0 -->
  <rentometer>
    ...
    <error id="0">Can't find that place... Please try again.</error>
  </rentometer>

JSON Formatted Requests

Valid JSON requests return a "200" status code and JSON (Javascript Object Notation) in the following format, for the above sample request (whitespace added for clarity). When there is insufficient data available to compute statistics (and the request is otherwise valid) values for the rental statistics will be returned as null and comps will not be returned.

  
  {
    generator: "http://www.rentometer.com",    
    beds: 2,
    rent: "$2,800",
    low_rent: "$550",
    entered: "2008-08-31T16:41:19Z",
    city:"Boston",
    state: "MA"
    zip: "02115",
    country: "US",
    latitude: 42.340411,
    longitude: -71.09286,
    bt: null,
    comps: [
        {
         latitude: 42.33918,    
         distance: "0.09 (miles)",
         longitude: -71.09223,
         rent: "$2,000"
        },
        {
         latitude: 42.33884,
         distance: "0.11 (miles)",
         longitude: -71.09248,
         rent: "$1,895"
        },
        ],
    median_rent: "$2,400",
    link: "http://www.rentometer.com/?show=results&beds=2&citystatezip=02... ,
    address: "Boston MA 02115",
    high_rent: "$5,200"
  }
  

Invalid Requests Examples (assuming verbose query parameter is used; HTTP status codes are set appropriately). Note that returned address here is from the request

  
 {error: {message: "ApiUser with token=.... could not be found", code: 401}}
 

  
 {errors: [
   "Please specify a valid positive number as your monthly rent.", 
   "Please specify between 0 and 8 bedrooms."
   ]
  }
  

If the Outbound API is unable to geocode (find) your location, it will return an error like:

  
  {errors: ["Can't find that place...  Please try again."]}
  

PNG Formatted Requests

Valid PNG requests return a "200" status code and an image in PNG format  for the above sample request (whitespace added for clarity). When there is insufficient data available to compute statistics (and the request is otherwise valid) values for the rental statistics will be omitted from the image.

Invalid Requests Examples (assuming verbose query parameter is used; HTTP status codes are set appropriately). Responses are returned as images.