HTTP conventions

The Reonomy HTTP API accepts JSON and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and methods.

Authentication

The API server authenticates all requests using HTTP Basic Authentication. You must include your access token in an Authorization request header with every API call, as shown in the example.

Your access token (YOUR_ACCESS_TOKEN) is a base64 encoding of your access key and secret key separated by a colon:

API_ACCESS_TOKEN = base64(access_key:secret_key)

If you enter your access and secret keys in the adjacent fields, you'll see the base64-encoded value in access token field.

Enter your access key

Enter your secret key

This is your access token

Hide access token

You can also copy and paste the user verification code sample shown on the right into an execution environment of your choice. For example:

Click the cURL tab.
Copy the code sample.
Paste it at a terminal prompt.
Press Enter to execute the cURL request.

Note: If you're using Postman, it can base64 encode your access key and secret key for you. See Using Postman.

Content negotiation

Responses

All endpoints return results in JSON. The API ignores any Accept header and always returns JSON.

Request bodies

POST requests require a Content-Type header indicating the media type of the resource you're including with the request. For POST requests with request bodies only (for example, POST /v2/search/summaries and POST /v2/resolve/property), the media type is always JSON (application/json).

Note: The batch API POST /v2/jobs/file endpoint has different requirements defined below.

Although the Content-Type header is required, client HTTP libraries and APIs typically insert the Content-Type header for you automatically based on the data specified in the request. Check your client library documentation for details.

Combining form data and files

The batch API's POST /v2/jobs/file endpoint and the bulk data feed's POST /v2/bulk-data-feeds/files endpoint require that you:

Specify the job type and any job metadata as a form object.
Specify the job details file as a files object.

Creating a low level HTTP request for this is tricky, so use of an HTTP client library is highly recommended. See the Batch job page for information on formatting these requests.

Important: Do not specify a Content-Type header when calling these endpoints. Client HTTP libraries will include the appropriate Content-Type header for you.

Rate limits

API requests are rate limited. For most endpoints, the rate limit is 5 requests per second.

If you exceed the rate limit for a given time period, the API returns HTTP status code 429 and you must wait before submitting additional requests.

For bulk property data, or to obtain the property IDs for large numbers of properties, we highly recommend using the API's batch job capability.

Status codes

Reonomy uses standard HTTP response codes to indicate the status of an API request. In general:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error due to an invalid request (for example, your API access token is missing or invalid, a required parameter is missing, the request body is improperly formatted, etc.).
Codes in the 5xx range indicate an error on Reonomy API server.

4xx errors may include an error message in the response object explaining the error. See Troubleshooting below for more information.

{
  "err_name": "AuthorizationException",
  "message": "No authentication method matched your request"
}

Troubleshooting HTTP 4xx errors

HTTP 400 (Bad request)

Status code 400 may indicate that your request is improperly formatted. Check the response for information about the problem. In the example, the request included an invalid settings attribute (town instead of city) and the error message provides information to help you fix the problem. Keep in mind the capitalization is important, so make sure all parameter names in your request match those shown in the API reference.

An HTTP 400 response may also indicate your account has no credits. Contact Customer Success if you need additional credits.

{
  "err_name": "ValidationError",
  "message": {
    "settings": {
      "town": [
        "Unknown field."
      ]
    }
  }
}

HTTP 401 (Unauthorized request)

Each call to the Reonomy API must include a valid access token (see Authentication above. Requests that do not include a valid access token will receive an HTTP 401 response with an error message:

If the authorization header is missing, the message is User isn't logged in.
If the supplied access token is invalid, the message is No authentication method matched your request

If you believe the access token your providing is valid, please contact Customer Success to verify the status of your account.

{
  "err_name": "AuthorizationException",
  "message": "User isn't logged in"
}

HTTP 404 (Not found)

The /v2/properties/{property_id} endpoint returns an HTTP 404 response if the API is unable to find a property for the ID you provided. 404 errors typically do not return a response message. Instead, you'll get the API server's standard 404 page, for example:



404 Not Found
Not Found
The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.

HTTP 429 (Too many requests)

All API endpoints are subject to rate limiting. If you exceed the the number of API calls you are permitted to make within a given time period, you'll receive an HTTP 429 response with a message indicating you've submitted too many requests.

If you receive a 429 error, you'll need to wait the appropriate amount of time before you can make additional calls. If you're trying to match or download data for large numbers of properties, try using the batch job API instead.

{
  "message": "Too many requests",
  "code": "TOO_MANY_REQUESTS"
}

Return to reonomy.com