NAV
DEVELOPER APIS
shell ruby javascript

Introduction

Included with your PRO Standard plan is access to the Rentometer API—a system that allows other applications to integrate Rentometer's rent analysis.

The API is in a beta release state and we welcome your feedback and suggestions.

API Credits

The cost of each endpoint is listed in the description below. A set of API Credits is included with your PRO Standard plan.

Additional credits can be purchased on the API Settings page.

Authentication

To check your authorization and credits available, use this code:

require 'net/http'

# auth (GET )
def send_request
  uri = URI('https://www.rentometer.com/api/v1/auth?api_key=RENTOMETER_API_KEY')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)

  # Create Request
  req =  Net::HTTP::Get.new(uri)

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
## auth
curl "https://www.rentometer.com/api/v1/auth?api_key=RENTOMETER_API_KEY"
// auth (GET https://www.rentometer.com/api/v1/auth)

jQuery.ajax({
    url: "https://www.rentometer.com/api/v1/auth",
    type: "GET",
    data: {
        "api_key": "RENTOMETER_API_KEY",
    },
})
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
})
.fail(function(jqXHR, textStatus, errorThrown) {
    console.log("HTTP Request Failed");
})
.always(function() {
    /* ... */
});
## Response JSON:
{
  "authorized": true,
  "account_email": "user@email.com",
  "credits_remaining": 7937,
  "pro_report_credits_remaining": 448
}

Make sure to replace RENTOMETER_API_KEY with your API key.

Rentometer uses API keys to allow access to the API. You can get a Rentometer API key at the API Settings page, which is accessible after establishing a PRO Standard subscription and accepting the terms of use.

Rentometer expects the API key to be included in all API requests to the server. It is not necessary to call the auth endpoint to use the API. It is provided to make it easier to work with some integration services (such as Zapier).

It can also be useful if you want to know how many credits remain on your account.

HTTP Request

GET https://www.rentometer.com/api/v1/auth

Query Parameters

Parameter Description
api_key Your API Key

Response JSON

Parameter Description
authorized Always returns true for a valid API key.
account_email Email address associated with your API key.
credits_remaining Number of API Credits remaining on your account.
pro_report_credits_remaining Number of PRO Report Credits remaining on your account.

Cost

0 API Credits

Rent Summary (QuickView)

To get a rent summary using an Address, use this code:

require 'net/http'

# Rent Summary (GET https://www.rentometer.com/api/v1/summary)
def send_request
  uri = URI('https://www.rentometer.com/api/v1/summary?api_key=RENTOMETER_API_KEY&address=15%20broad%20st.,%20boston,%20ma&bedrooms=2&baths=1.5%2B&building_type=house')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)

  # Create Request
  req =  Net::HTTP::Get.new(uri)

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
## Rent Summary
curl "https://www.rentometer.com/api/v1/summary?api_key=RENTOMETER_API_KEY&address=15%20broad%20st.,%20boston,%20ma&bedrooms=2&baths=1.5%2B&building_type=house"
// Rent Summary (GET https://www.rentometer.com/api/v1/summary)

jQuery.ajax({
    url: "https://www.rentometer.com/api/v1/summary",
    type: "GET",
    data: {
        "api_key": "RENTOMETER_API_KEY",
        "address": "15 broad st., boston, ma",
        "bedrooms": "2",
        "baths": "1.5+",
        "building_type": "house",
    },
})
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
})
.fail(function(jqXHR, textStatus, errorThrown) {
    console.log("HTTP Request Failed");
})
.always(function() {
    /* ... */
});
## Response JSON:
{
  "address": "15 Broad Street, Boston, Massachusetts 02109",
  "latitude": "42.358729",
  "longitude": "-71.054801",
  "bedrooms": 2,
  "baths": "1.5+",
  "building_type": "House",
  "mean": 2990,
  "median": 2950,
  "min": 2500,
  "max": 3560,
  "percentile_25": 2666,
  "percentile_75": 3315,
  "std_dev": 481,
  "samples": 4,
  "radius_miles": 3.0,
  "quickview_url": "https://www.rentometer.com/analysis/2-bed/15-broad-street-boston-massachusetts-02109/8sGt-WiSehg/quickview",
  "credits_remaining": 7925,
  "token": "YPZ4RNaAqUw",
  "links": [
    {
      "rel": "request pro report",
      "href": "/api/v1/request_pro_report?api_key=RENTOMETER_API_KEY&token=8sGt-WiSehg"
    }
  ]
}

Make sure to replace RENTOMETER_API_KEY with your API key.

The Rent Summary endpoint, a.k.a. the QuickView, is the starting point for all rent analysis via the API. It returns a summary of the rent for a given address, along with a link to the QuickView that is viewable in a web browser.

Additionally, the QuickView endpoint returns a token that can be used to request a PRO Report.

HTTP Request

GET https://www.rentometer.com/api/v1/summary

Query Parameters

Parameter Description
api_key Your API Key
address Address describing the center point of analysis. Will be geocoded. Alternatively, provide a latitude/longitude directly. Important: Addresses often include characters that will cause an API call to fail. Be sure to URL Encode your address before including it in the request to avoid an invalid URL.
latitude Latitude of the center point of analysis. Can be provided along with longitude as an alternative to address.
longitude Longitude of the center point of analysis. Can be provided along with latitude as an alternative to address.
bedrooms Number of bedrooms. Valid values are: 1, 2, 3, or 4.
baths Optional. Restrict listings to those with only 1 bathroom or 1.5+. Valid values are: blank, "1", or "1.5+". Note: not all listings include this information and may be excluded from the results.
building_type Optional. Restrict listings to Apartments/Condos or Houses/Duplexes. Valid values are: blank, "apartment", or "house". Note: not all listings include this information and may be excluded from the results.

Response JSON

Parameter Description
address Search address after being formatted by the geocoder. Blank if only lat/lng were provided.
latitude Latitude of the center point of analysis.
longitude Longitude of the center point of analysis.
bedrooms Number of bedrooms used in Analysis.
baths Number of bathrooms used in Analysis.
building_type Building type used in Analysis.
mean Mean rent in the area analyzed.
median Median rent in the area analyzed.
min Minimum rent in the area analyzed.
max Maximum rent in the area analyzed.
percentile_25 25th percentile rent in the area analyzed.
percentile_75 75th percentile rent in the area analyzed.
std_dev Standard deviation of rent in the area analyzed.
samples Number of listings analyzed.
radius_miles Radius of the area analyzed. This is auto-selected based on the density of listings in the area.
quickview_url URL to the QuickView page for the analysis.
credits_remaining API credits remaining.
token Unique token for the analysis. This can be used to request a Pro Report for this analysis.
links Array of links to other API endpoints that may be of interest.

Cost

1 API Credit

PRO Reports

The PRO Report endpoint allows you to request a PRO Report for a given analysis. The QuickView endpoint returns a token that can be used to request a PRO Report, so you'll always start with a request to the Rent Summary endpoint first.

The PRO Report takes time to generate, so this endpoint operates in an asynchronous manner.

Once generated, a PRO Report can be downloaded in the form of a PDF.

In the future, endpoints may be added to mirror other PRO Report functionality available on the interactive site (e.g., a CSV of the sample data, sharing a report via email, etc.). If you are interested in these or other features we welcome your feedback!

Request PRO Report

To get a PRO Report, use this code:

require 'net/http'

# Request Pro Report (GET https://www.rentometer.com/api/v1/request_pro_report)
def send_request
  uri = URI('https://www.rentometer.com/api/v1/request_pro_report?api_key=FWJf4HBOEzlKFmd6knMVnA&token=YPZ4RNaAqUw')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)

  # Create Request
  req =  Net::HTTP::Get.new(uri)

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
## Request Pro Report
curl "https://www.rentometer.com/api/v1/request_pro_report?api_key=FWJf4HBOEzlKFmd6knMVnA&token=YPZ4RNaAqUw"
// Request Pro Report (GET https://www.rentometer.com/api/v1/request_pro_report)

jQuery.ajax({
    url: "https://www.rentometer.com/api/v1/request_pro_report",
    type: "GET",
    data: {
        "api_key": "FWJf4HBOEzlKFmd6knMVnA",
        "token": "YPZ4RNaAqUw",
    },
})
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
})
.fail(function(jqXHR, textStatus, errorThrown) {
    console.log("HTTP Request Failed");
})
.always(function() {
    /* ... */
});

The above code will return a JSON response similar to this:

## HTTP/1.1 202 Accepted
{
  "status": "added to queue",
  "token": "YPZ4RNaAqUw",
  "pro_report_credits_remaining": 446,
  "links": [
    {
      "rel": "check status",
      "href": "/api/v1/pro_report_status?api_key=RENTOMETER_API_KEY&token=YPZ4RNaAqUw"
    }
  ]
}

Make sure to replace RENTOMETER_API_KEY with your API key.

This endpoint will initiate the generation of a PRO Report for the given analysis. Assuming a valid token, the endpoint will immediately return an HTTP 202: Accepted response.

The response will include a link to the endpoint that can be used to check the status of the PRO Report.

HTTP Request

GET https://www.rentometer.com/api/v1/request_pro_report

Query Parameters

Parameter Description
api_key Your API Key
token Unique token for the analysis. This can be obtained from the QuickView endpoint.

Response JSON

Parameter Description
status Status of the PRO Report. Will always be "added to queue".
pro_report_credits_remaining API credits remaining.
token Unique token for the analysis.
links Array of links to other API endpoints that may be of interest. In particular, the status endpoint can be used to check the status of the PRO Report.

Cost

1 PRO Report Credit, 0 API Credits

PRO Report Status

To check the status of a PRO Report, use this code:

require 'net/http'

# Pro Report Status (GET https://www.rentometer.com/api/v1/pro_report_status)
def send_request
  uri = URI('https://www.rentometer.com/api/v1/pro_report_status?api_key=RENTOMETER_API_KEY&token=YPZ4RNaAqUw')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)

  # Create Request
  req =  Net::HTTP::Get.new(uri)

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
## Pro Report Status
curl "https://www.rentometer.com/api/v1/pro_report_status?api_key=RENTOMETER_API_KEY&token=YPZ4RNaAqUw"
// Pro Report Status (GET https://www.rentometer.com/api/v1/pro_report_status)

jQuery.ajax({
    url: "https://www.rentometer.com/api/v1/pro_report_status",
    type: "GET",
    data: {
        "api_key": "RENTOMETER_API_KEY",
        "token": "YPZ4RNaAqUw",
    },
})
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
})
.fail(function(jqXHR, textStatus, errorThrown) {
    console.log("HTTP Request Failed");
})
.always(function() {
    /* ... */
});

This response indicates the report is still being generated:

# HTTP 202 Accepted
{
  "status": "in queue, retry later",
  "retry_after": 5,
  "token": "YPZ4RNaAqUw",
  "links": [
    {
      "rel": "check status",
      "href": "/api/v1/pro_report_status?api_key=RENTOMETER_API_KEY&token=YPZ4RNaAqUw"
    }
  ]
}

This response indicates the report is ready for download:

# HTTP 303 See Other
{
  "status": "ready",
  "token": "YPZ4RNaAqUw",
  "links": [
    {
      "rel": "download",
      "href": "https://www.rentometer.com/api/v1/download_pro_report?api_key=RENTOMETER_API_KEY&token=YPZ4RNaAqUw"
    }
  ]
}

Make sure to replace RENTOMETER_API_KEY with your API key.

This endpoint check the status of the PRO Report. Assuming a valid token, the endpoint will return either an HTTP 202: Accepted response or an HTTP 303: See Other response.

If the report is still being generated, the endpoint will return a HTTP 202: Accepted response, along with a link back to this same status endpoint. The Retry After header will be set to the recommended wait time in seconds. Building a PRO Report usually takes 5-10 seconds, but this can vary depending on the area being analyzed, how busy the service is, internet weather conditions, etc.

If the report is ready, the endpoint will return a HTTP 303: See Other response, along with a link to the download PRO Report endpoint. The Location header will be set to the download PRO Report endpoint in case your API client is able to handle the redirect automatically; otherwise you may pull the link from the response JSON.

HTTP Request

GET https://www.rentometer.com/api/v1/pro_report_status

Query Parameters

Parameter Description
api_key Your API Key
token Unique token for the analysis.

Response JSON

Parameter Description
status Status of the PRO Report.
retry-after Suggested wait time before retry in seconds.
token Unique token for the analysis.
links Array of links to other API endpoints that may be of interest.

Cost

0 API Credits

Download PRO Report

To download a PRO Report PDF, use this code:

require 'net/http'

# Download Pro Report (GET https://www.rentometer.com/api/v1/download_pro_report)
def send_request
  uri = URI('https://www.rentometer.com/api/v1/download_pro_report?api_key=FWJf4HBOEzlKFmd6knMVnA&token=YPZ4RNaAqUw')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)

  # Create Request
  req =  Net::HTTP::Get.new(uri)

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
## Download Pro Report
curl "https://www.rentometer.com/api/v1/download_pro_report?api_key=FWJf4HBOEzlKFmd6knMVnA&token=YPZ4RNaAqUw"
// Download Pro Report (GET https://www.rentometer.com/api/v1/download_pro_report)

jQuery.ajax({
    url: "https://www.rentometer.com/api/v1/download_pro_report",
    type: "GET",
    data: {
        "api_key": "FWJf4HBOEzlKFmd6knMVnA",
        "token": "YPZ4RNaAqUw",
    },
})
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
})
.fail(function(jqXHR, textStatus, errorThrown) {
    console.log("HTTP Request Failed");
})
.always(function() {
    /* ... */
});

The response will be similar to:

{
  "status": "PRO Report Ready",
  "token": "YPZ4RNaAqUw",
  "links": [
    {
      "rel": "download",
      "href": "https://rentometer-assets-dev.s3.amazonaws.com/search_pdfs/20210923-Rentometer-15_Broad_Street_Boston_Massachusetts_02109_United_States-2-bed-YPZ4RNaAqUw.pdf?1632411741"
    }
  ]
}

Make sure to replace RENTOMETER_API_KEY with your API key.

This endpoint will provide a URL where you can download a PDF version of the PRO Report.

HTTP Request

GET https://www.rentometer.com/api/v1/download_pro_report

Query Parameters

Parameter Description
api_key Your API Key
token Unique token for the analysis. This can be obtained from the QuickView endpoint.

Response JSON

Parameter Description
status Status of the PRO Report.
token Unique token for the analysis.
links Array of links to other API endpoints that may be of interest. In particular, the download link will be set to the location of the PDF file.

Cost

0 API Credits

Errors

The Rentometer API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
402 Payment Required -- You need to purchase additional API Credits.
404 Not Found -- The specified token could not be found.
429 Too Many Requests -- You're requesting too many reports! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.