Overview

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

The API is split into two main endpoints, one for property type requests and one for locale/neighborhood information. The endpoint for your key will be shown in the key details within your dashboard.


Get an API Key

All API calls must include a valid API key, this is our way of identifying you and authorizing your call. The first key you receive will be a trial key for the package/bundle you have chosen, and will include 200 free calls. If you require more to develop your application, please contact us.

Get a key

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"}]/td>

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.

The request

Locales can be searched at a several different levels. The results will be returned on the level specified, or the next higher level on the geographical hierarchy. Choose the level you want from the available search parameters below.

All requests:

https://factory.datanerds.com/api/v2/locale?api_key=your_key_here&county=Harris&state=TX

Available search parameters:

  • zipcode
  • latitude & longitude
  • city_name & state
  • city_fips
  • census_tract & state
  • county_name & state
  • county_fips

Input parameter formats:

Name: Type: Format:
zipcode
integer
5 digit code
latitude
decimal
Decimalized latitude, with any number of decimal places up to 8
longitude
decimal
Decimalized longitude, with any number of decimal places up to 8
city_name
string
City name. Must be accompanied by state
state
string
2 Character state abbreviation
city_fips
integer
5 digit city fips code
census_tract
integer
6 digit census tract code. Must be accompanied by state
county_name
string
County name. Must be accompanied by state
county_fips
integer
5 digit county fips code (2 digit state + 3 digit county)

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
    },
    "locale": {a locale object}
}

Error response: (View error codes)

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