V4 Documentation

Migrating to v4 from v3

Migrating to the latest and greatest API version should be made simple. We've documented all our changes below to help facilitate just that.

Making a request

Endpoint

The very first thing to note is that the endpoint URL has changed. All requests must now hit the https://apis.estated.com/v4/property endpoint.

API Keys

If you are unsure if your key is compatible with v4, please contact support@estated.com and a representative will be happy to help you.

Request Methods

In v4, the request methods have changed. Properties are now queryable in the following ways:

Combined address
Split address
Parsed address
FIPS code + APN

Note: The API no longer supports XML response type.

Parsing responses

Success response

At the highest level, a successful response (200 http status code) will contain a payload with the following data in the body: metadata, data and warnings. If a property record is found, the data will appear in the data field. If a property was not found, a list of reasons will be found in the warnings field.

{
    "success": true,
    "codes": {},
    "properties": [{ ... }]
}

{
    "metadata": {},
    "data": {},
    "warnings": [{ ... }]
}

Error response

At the highest level, an error response (4xx, 5xx http status codes) will contain a payload with the following data in the body: metadata, data and errors. The data field will be set to null and a list of errors can be found in the errors field.

{
    "success": false,
    "codes": {
        "RE02": "Invalid token"
    }
}

{
    "error": { ... }
    "metadata": {},
}

Schema Changes

data

A successful request where a property match is found will contain the property record in the data field. With the data object's components listed, a response looks like the following:

{
    "success": true,
    "codes" : { },
    "properties": [
        {
            "metadata": { ... },
            "addresses": [{ ... }],
            "geocoding": { ... },
            "parcel": { ... },
            "land_use": { ... },
            "structures": [{ ... }],
            "structure_totals": { ... },
            "owners": [{ ... }],
            "assessments": [{ ... }],
            "sales": [{ ... }],
            "mortgages": [{ ... }],
            "legal": { ... },
            "valuation": { ... },
            "status": { ... },
            "postal": { ... },
            "geographies": { ... }
        },
        ...
    ]
}

{
    "metadata": {},
    "data": {
        "metadata": { ... },
        "address": { ... },
        "parcel": { ... },
        "structure": { ... },
        "taxes": [{ ... }],
        "assessments": [{ ... }],
        "market_assessments": [{ ... }],
        "valuation": { ... }
        "owner": { ... },
        "deeds": [{ ... }],
    },
    "warnings": [{ ... }]
}

data.metadata

The metadata object has been reduced to the following property: publishing_date.

"metadata": {
    "property_id": 17535291,
    "published_at": "2015-08-18",
    "updated_at": "2018-09-28"
    "upi": "US-06037-N-4328031029-R-N",
    "release_version": "v57.2"
}

"data": {
    "metadata": {
        "publishing_date": "2015-08-18",
    }
}

data.address

The addresses section from v3 has been renamed to address and now includes one record per property. There are 6 new fields: unit_type, carrier_code, latitude, longitude, geocoding_accuracy, census_tract.

"addresses": [
    {
        "street_number": "220",
        "street_pre_direction": "S",
        "street_name": "Rodeo",
        "street_suffix": "Dr",
        "street_post_direction": null,
        "unit_number": null,
        "formatted_street_address": "220 S Rodeo Dr",
        "city": "Beverly Hills",
        "state": "CA",
        "zip_code": "90212",
        "zip_code_plus_four": "3804"
    }
]

"address": {
    "street_number": "3450",
    "street_pre_direction": "N",
    "street_name": "MAIN",
    "street_suffix": "ST",
    "street_post_direction": null,
    "unit_type": "APT",
    "unit_number": "101A",
    "formatted_street_address": "3450 N MAIN ST APT 101A",
    "city": "CHICAGO",
    "state": "IL",
    "zip_code": "60614",
    "zip_code_plus_four": "5505",
    "carrier_code": "R001",
    "latitude": 41.912406",
    "longitude": -87.649191",
    "geocoding_accuracy": "ROOFTOP",
    "census_tract": "10570200.002009",
}

data.parcel

"parcel": {
    "depth": 128,
    "width": 55,
    "size": 2748,
    "acres": 0.161,
    "range": null,
    "township": null,
    "section": null,
    "block": null,
    "lot": null,
    "location_description": null,
    "building_count": 1,
    "boundaries": { ... }
}

"parcel": {
    "apn_original": "001-090-04-02",
    "apn_unformatted": "0010900402",
    "apn_previous": "001-090-04-00",
    "fips_code": 12086,
    "depth_ft": 128,
    "frontage_ft": 55,
    "area_sq_ft": 2748,
    "area_acres": 0.161,
    "county_name": "COOK",
    "county_land_use_code": "SFR01",
    "county_land_use_description": "RESIDENTIAL SINGLE DWELLING",
    "standardized_land_use_category": "SINGLE FAMILY RESIDENTIAL",
    "standardized_land_use_type": "TOWNHOUSE",
    "location_descriptions": { ... },
    "zoning": "T/G",
    "building_count": 1,
    "tax_account_number": "0134601209K",
    "legal_description": "LEGAL SUBDIVISION 4, SECTION 10, TOWNSHIP 82, WEST OF THE 6TH MERIDIAN, NEW YORK DISTRICT",
    "lot_code": "MORE THAN ONE",
    "lot_number": "1-13,15",
    "subdivision": "CRYSTAL LAKE FOREST",
    "municipality": "FELL TOWNSHIP",
    "section_township_range": "SEC 14 TWN 1N RNG 11E",
}

data.structure

The structures section from v3 has been renamed to structure and now includes one record per property, although this component may have reference to other structures on the property.

"structures": [
    {
        "year_built": 1926,
        "effective_year_built": 1965,
        "identifier": null,
        "rooms_count": 8,
        "beds_count": 3,
        "baths_count": 4,
        "half_baths_count": null,
        "full_baths_count": 4,
        "quarter_baths_count": null,
        "three_quarter_baths_count": null,
        "stories_count": 1,
        "units_count": 1,
        "total_size": 2748,
        "finished_size": 2748,
        "unfinished_size": 0,
        "basement_size": null,
        "garage_size": null,
        "height": null,
        "architecture_type": "Spanish",
        "exterior_wall_type": "Stucco",
        "air_conditioning_type": "Central",
        "basement_type": null,
        "building_type": null,
        "category": "Single family",
        "condition": null,
        "construction_type": null,
        "fireplace_count": 1,
        "fireplace_type": null,
        "foundation_type": "Raised",
        "flooring_type": null,
        "garage_type": null,
        "heating_type": "Central",
        "mobile_home": null,
        "parking_spaces": 2,
        "parking_type": "On Site",
        "pool_type": null,
        "quality": null,
        "roof_type": null,
        "roof_style_type": null,
        "electricity_type": null,
        "fuel_type": null,
        "sewer_type": null,
        "water_type": null,
        "is_primary": true
    }
]

"structure": {
    "year_built": 1926,
    "effective_year_built": 1965,
    "stories": "2+A",
    "rooms_count": 8,
    "beds_count": 3,
    "baths": 2.5,
    "partial_baths_count": 2,
    "units_count": 1,
    "parking_type": "DETACHED GARAGE",
    "parking_spaces_count": 2,
    "pool_type": "HEATED POOL",
    "architecture_type": "SPANISH",
    "construction_type": "WOOD",
    "exterior_wall_type": "STUCCO",
    "foundation_type": "CONCRETE",
    "roof_material_type": "ASPHALT",
    "roof_style_type": "GABLE",
    "heating_type": "BASEBOARD",
    "heating_fuel_type": "GAS",
    "air_conditioning_type": "CENTRAL",
    "fireplaces": 2,
    "basement_type": "FINISHED",
    "quality": "A+",
    "condition": "FAIR",
    "flooring_types": { ... },
    "plumbing_fixtures_count": 1,
    "interior_wall_type": "PLASTER",
    "water_type": "MUNICIPAL",
    "sewer_type": "SEPTIC",
    "total_area_sq_ft": 1692,
    "other_areas": [{ ... }],
    "other_features": [{ ... }],
    "other_improvements": [{ ... }],
    "other_rooms": { ... },
    "amenities": { ... }
}

data.taxes, data.assessments, data.market_assessments

The assessments section from v3 has been split up into 3 new components: taxes, assessments, and market_assessments

"assessments": [
    {
        "land": 2201657,
        "improvement": 954935,
        "total": 3156592,
        "tax_amount": 36007,
        "tax_year": 2016,
        "details": null,
        "outstanding_tax": null,
        "appraised_total": null,
        "appraised_land": null,
        "appraised_improvement": null,
        "exemptions": null
    },
    ...
]

"taxes": [
    {
        "year": 2017,
        "amount": 2247,
        "exemptions": { ... },
        "rate_code_area": "01H"
    },
    ...
],
"assessments": [
    {
        "year": 2018,
        "land_value": 2580,
        "improvement_value": 13300,
        "total_value": 15880
    },
    ...
],
"market_assessments": [
    {
        "year": 2017,
        "land_value": 3000,
        "improvement_value": 12000,
        "total_value": 15000
    },
    ...
]

data.valuation

"valuation": {
    "value": 3701176,
    "low": null,
    "high": null,
    "confidence": null,
    "market_value_change_year": null,
    "market_value_change_quarter": null,
    "forecast_1_year": 3832873,
    "calculated_rental_value": null
}

"valuation": {
    "value": 16430,
    "low": 15780,
    "high": 17220,
    "confidence": 75,
    "forecast_deviation": 55,
    "date": "2019-10-24",
}

data.owner

The owners section from v3 has been renamed to owner and now includes one record per property. This record will be from either the assessment or the deeds, whichever is more recent.

"owners": [
    {
        "corporate_flag": false,
        "name": "SMITH JOHN",
        "second_name": null,
        "address": "610 N Beverly Dr",
        "city": "Beverly Hills",
        "state": "CA",
        "zip_code": "90210",
        "first_name": "JOHN",
        "middle_name": null,
        "last_name": "SMITH",
        "suffix": null,
        "ended_at": null,
        "started_at": "2013-04-02"
    },
    ...
]

"owner": {
    "name": "JOHN SMITH",
    "second_name": "JANE SMITH",
    "address": "123 MAIN ST",
    "unit_type": "STE",
    "unit_number": "104",
    "city": "ATLANTA",
    "state": "GA",
    "zip_code": "90210",
    "zip_plus_four_code": "3019",
    "owner_occupied": "YES",
}

data.deeds

The sales and mortgages sections from v3 have been merged and now make up the deeds component.

"sales": [
    {
        "date": "2013-04-02",
        "recording_date": "2013-04-12",
        "price": 2975000,
        "type": "Grant Deed",
        "seller": "SMITH JOHN & JANE",
        "buyer": null,
        "transaction_id": "201304172813",
        "document_year": 2013,
        "sale_code": "Sale Price (Full)",
        "multi_apn": false,
        "hpi_adjusted_price_2010": 2876665,
        "deed_book": null,
        "deed_page": null,
        "document_id": 2468
    },
    ...
],
"mortgages": [
    {
        "amount": 399877,
        "loan_type": "Federal Housing Authority",
        "deed_type": "Deed Of Trust",
        "date": "2017-06-23",
        "term": 360,
        "due_date": null,
        "lender_name": null,
        "details": null
    },
    ...
]

"deeds": [
    {
        "document_type": "WARRANTY DEED",
        "recording_date": "2011-12-28",
        "original_contract_date": "2011-12-26",
        "deed_book": "9056",
        "deed_page": "595",
        "document_id": "93154L",
        "sale_price": 170000,
        "sale_price_description": "FULL AMOUNT STATED ON DOCUMENT",
        "transfer_tax": 142.03,
        "distressed_sale": "FALSE",
        "real_estate_owned": "YES",
        "seller_first_name": "JOHN",
        "seller_last_name": "SMITH",
        "seller2_first_name": "JANE",
        "seller2_last_name": "SMITH",
        "seller_address": "123 MAIN ST",
        "seller_unit_number": "1",
        "seller_city": "PHOENIX",
        "seller_state": "AZ",
        "seller_zip_code": "85024",
        "seller_zip_plus_four_code": "3019",
        "buyer_first_name": "JOHN",
        "buyer_last_name": "SMITH",
        "buyer2_first_name": "JANE",
        "buyer2_last_name": "SMITH",
        "buyer_address": "123 MAIN ST",
        "buyer_unit_type": "APT",
        "buyer_unit_number": "1A",
        "buyer_city": "DENVER",
        "buyer_state": "CO",
        "buyer_zip_code": "80222",
        "buyer_zip_plus_four_code": "3019",
        "lender_name": "CITIMORTGAGE INC",
        "lender_type": "BANK",
        "loan_amount": "74900",
        "loan_type": "CREDIT LINE (REVOLVING)",
        "loan_due_date": "2029-10-22",
        "loan_finance_type": "FIXED RATE",
        "loan_interest_rate": 2.97,
    },
    ...
]