Overview

Welcome to the documentation. We have created a simple, easy to use API and have done our best to document each feature here.


Return values

Values returned will match the data type as specified for each field in the schema (integer, string, decimal, etc). The possible values for each datatype is shown below.

Absence describes when it is known that a feature does not exist, Unknown describes when the data could not be found. For example, if a property does not have a garage, the garage_size field will return "0". If we don't have data on whether it has a garage or not, the return value will be NULL.

Data type Absence Unknown (data unavailable) Value
Integer 0 NULL Natural number
Decimal 0 NULL Decimal number
String Empty string NULL String
Boolean false NULL true/false
Date Empty string NULL YYYY-MM-DD
Datetime Empty string NULL YYYY-MM-DD HH:MM:SS
JSON string [{"field":""}] [{"field":NULL}] [{"field":"value"}]

Errors

Errors happen either because of a problem occurred with the key or the request. The level at which the result provides an error differs based on where the error occurs within the request.

Error message Description
No key provided No key was provided in the api_key parameter of the request.
Invalid Key Key supplied in the api_key parameter of the request is not a valid key.
Key disabled Key supplied in the api_key parameter of the request has been disabled.
Trial limit reached Key supplied in the api_key parameter of the request has reached its trial call limit.
Unpaid account The account which owns the key has an unpaid balance.
Missing search parameters There was not enough search parameters supplied to complete the request.
No results We were unable to find results for the request.
Failed General failure, usually specific to an internal problem with the api (rare occurrence).

The request

Properties can be requested by a variety of methods. Choose the method below based on what works best for your application.

Conforming address type:

https://factory.datanerds.com/api/v2/property?api_key=your_key_here&address=151+Battle+Green+Dr&city=Rochester&state=NY&zipcode=14624
Required fields:
  • address
  • city
  • state
Optional fields:
  • zipcode

Fully qualified type:

https://factory.datanerds.com/api/v2/property?api_key=your_key_here&unit_number=B&unit_type=Apt&street_number=1514&street_name=Harvard&street_suffix=Avenue&city=Arlington+Heights&state=IL&zipcode=50012
Required fields:
  • street_number
  • street_name
  • street_suffix
  • city
  • state
Optional fields:
  • unit_number
  • unit_type
  • street_direction
  • zipcode

Conjoined type:

https://factory.datanerds.com/api/v2/property?api_key=your_key_here&conjoined_address=151+Battle+Green+Dr,Rochester,NY+14624
Elements in string, separated by commas. Optional elements in brackets:
  • (unit number + unit type) + street number + street name + street suffix
  • city
  • state + zipcode

Property Id:

https://factory.datanerds.com/api/v2/property?api_key=your_key_here&property_id=945046
Required fields:
  • property_id

The response

Responses include a result with a status, and an error message if applicable. The second parameter of the response will be the property object if the result status is successful, or a null value otherwise.

Successful response:

{
    "result": {
        "status": "success",
        "code": 200
    },
    "property": {a property object}
}

Error response: (View error codes)

{
    "result": {
        "status": "error",
        "code": 400,
        "message": "Invalid API key"
    },
    "property": null
}

The property object

A successful call will include a property object.

"property": {
    "metadata": {
        "property_id": "",
        "address_match": "exact"
    },
    "site": {a site object},
}

The address_match field indicates how closely the result matches the parameters of the requested property. There are three possible result codes:

exact - The result is an exact match for the request.

close - An exact match wasn’t possible, but a result that closely matches the address was found.

guess - Multiple results were possible from the request parameters, a result was returned out of the possible properties based on a best guess algorithm.

Note: If we did not find any results for the requested address, that will be returned in the result portion of the response, with a 404 error code.