top of page
top_of_page

DwellingCost.com Application Programming Interface (API)

Version: 4.6.0

Latest Release: July 28, 2023

Overview & Contents

This documentation supports DwellingCost.com's Application Programming Interface (API) for its Appraiser Replacement Cost Estimator Product (v4.5). The DwellingCost.com API is a simple web application that handles property-level request(s) extending DwellingCost.com’s proprietary data for use in endless applications/integrations. This document contains programmer’s reference and general development guidelines. DwellingCost.com supports REST API protocol standards communicated over HTTPS (primarily using JSON-encoded files). Sample files are provided where necessary.

Note the DwellingCost API is intended to deliver the simplicity and efficiency of our web application with the flexibility to integrate directly into your existing systems and products. As such, the best way to get a feel for the system, and the fields the API will request, is to become very familiar with our existing web application. As you develop, don't forget to sign up for your free trial here.

This documentation assumes that the user holds the necessary and approved DwellingCost.com Web Services credentials to interface with DC Web Services products (more information here). The request endpoint, report key, and report endpoint have been provided in your Web Services portal.

In making your first API call, we recommend following step-by-step from Section 1 to Section 3, which is the minimum requirement to get a valid response. Sections 4 through 9 detail various add-ons and improvements you can add to a property request once connected.

Documentation Contents:

  1. Making a Request

  2. Authenticating with the DwellingCost API

  3. Replacement Cost Estimates for Stick-Built Dwellings

    1. Single-Family Site-Built Dwelling Example

    2. Providing Below-Grade GLA per ANSI Z765-2021 Measurement Standard

    3. Multi-Family Dwellings

    4. Multi-Family Site-Built Dwelling Example

  4. Replacement Cost Estimates for Manufactured Homes

    1. Manufactured Homes Example​

  5. Requesting Additional Dwelling Components:

    1. Built-In/Attached Garage Cost Estimate

    2. Detached Garage Cost Estimate

    3. Carport Cost Estimate

    4. Attic Cost Estimate

    5. Basement Cost Estimate​

    6. Additional Dwelling Component Example

  6. Requesting Additional Structures:​

    1. Accessory Dwelling Unit (ADU) / Guest House Cost Estimate​

    2. Shed Cost Estimate

    3. Workshop Cost Estimate

    4. Bonus Room Cost Estimate

    5. Barn Cost Estimate

    6. Using DwellingCost to Calculate Additional Structure Quality Ratings

    7. Additional Structure Example

  7. Requesting Additional Site Improvements:

    1. Uncovered / Deck Cost Estimate​

    2. Covered Patio / Gazebo Cost Estimate

    3. Enclosed Patio Cost Estimate

    4. Pool Cost Estimate

    5. Additional Site Improvement Example

  8. Requesting Any Cost Element Ad Hoc​

    1. Example Ad Hoc Barn Request​

  9. Generating DwellingCost.com Reports with PDF Download​

    1. Report Annotations (Does Not Impact Cost Estimate)​

    2. Example request with report annotations

Version 4 of the DwellingCost API is designed to be fully backwards compatible with prior versions and requires no changes to current deployments to update, with the sole exception being for Manufactured Homes requests run under API v3. Click here for documentation relating to API v3.

contents

1.0 - Making a Request

secton_1.0

Method: GET, POST

Endpoint: https://<url_in_web_services_portal>.com/dcrequests

The DwellingCost API is designed to enable the user to pull all replacement cost estimates for a relevant property in a single API call; therefore, all of the components described below can be provided as one JSON or provided ad hoc for any individual component. Additionally, one search (i.e., API request) can contain up to thirty properties to enable a subject property and a set of comparable properties to be run simultaneously. However, please note that API list pricing is assessed on a per property basis (versus per search).

A request is a JSON file with two sections: the checkfields parameter (as described in Section 2.0) and the Request parameter; the response will be passed back with a Result parameter. Requests can be made using either GET or POST HTTP protocols. An example cURL statement making a valid dwelling request is as follows:

curl --request POST 'https://<url_in_web_services_portal>.com/dcrequests' --header 'Content-Type: application/json' \
--data-raw "{
    "checkfields": [
        {
            "account": "123456789abcdefghijklmnopqrstuvwxyz",
            "secret": "zyxwvutsrqponmlkjihgfedcba987654321"
        }
    ],
    "Request": [{

       "propnum": 0,

       "month": 1,

       "day": '1',

       "year": '2022',

       "address": "12345 Sample Avenue",

       "zip": "91355",

       "quality": 3.5,

       "gla": 2200,

       "bath_full": 2,

       "bath_half": 0,

       "stories": 2
    }]
}"

2.0 - Authenticating with the DwellingCost API

section_2.0

DwellingCost's API utilizes a two-step OAuth2.0 authentication engine which for efficiency and security is fully authenticated server-side. As such, authenticating with the DwellingCost API is as easy as passing your JSON credentials with the property request itself. Each request should include a Request parameter and a checkfields parameter; the latter should include your account and secret credentials. Sample JSON as follows:

{"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }]

}

section_3.0

3.0 - Replacement Cost Estimates for Site-Built Dwellings {dwelling_result}

As referenced in Authenticating with the DwellingCost API, each request should include a Request parameter and a checkfields authentication parameter. Note that the JSON for all fields should have all properties masked as a string, and that the field types in this documentation should otherwise be observed within that string (for instance, an integer to represent the month of January should be passed as string '1'). To run a single-family Site-Build dwelling, the following fields must be provided:

  • propnum [integer]: An integer (should begin at 0) used to identify individual properties in a batch request

  • year [integer]: The effective year of the replacement cost estimate; format yyyy

  • month [integer]: The effective month of the replacement cost estimate; format m

  • day [integer]: The effective day of the replacement cost estimate; format d

  • address [string]: Reflects property address; maximum 255 characters

  • zip [string]: Five character zip code as recognized by USPS (note: you must include any leading or trailing zeroes to get an accurate result)

  • quality [number]: The quality rating of the dwelling building materials on the DwellingCost scale from 1.0 to 8.0, with increments of 0.1 allowed

  • gla [integer]: Gross living area for the dwelling

  • bath_full [integer]: Number of full baths within the dwelling

  • bath_half [integer]: Number of half baths within the dwelling

  • stories [number]: Number of stories within the dwelling (maximum of 4.0; increments of 0.5 allowed)

3.1 - Example of Single Family Site-Build Dwelling Request
section_3.1

These minimum required fields should be passed, with the appropriate checkfields credentials in a JSON file as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       "propnum": 0,

       "month": 1,

       "day": '1',

       "year": '2022',

       "address": "12345 Sample Avenue",

       "zip": "91355",

       "quality": 3.5,

       "gla": 2200,

       "bath_full": 2,

       "bath_half": 0,

       "stories": 2

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": null, 

      "basement_result": null, 

      "carport_result": null, 

      "covered_result": null, 

      "deck_result": null, 

      "dgarage_result": null, 

      "dwelling_result": 149.73040267575863, 

      "enclosed_result": null, 

      "garage_result": null, 

      "jobid_v3": <redacted>, 

      "pool_result": null, 

      "propnum": 0

    }

  ]

}

3.2 - Providing Below-Grade GLA per ANSI Z765-2021 Measurement Standard
section_3.2

The ANSI standard requires any living area that is partially or wholly below grade to be counted separate from the dwelling's gross living area. DwellingCost supports this methodology if the following fields are provided:

  • ansi_gla_bin [binary]: Pass as true to enable any of the features in this section; mark False or omit if search does not include any additional structures. Note, variable needs to be passed as a logical-encoded True value, and if you pass any variables from this section but do not pass a True value for this variable, your response will not include any additional structure outputs

  • ansi_gla [integer]: Below-grade gross living area in square feet

Note: if ANSI GLA is provided, it should be excluded from the GLA provided in Section 3.0. The sum of the GLA and ANSI GLA should reflect the total gross living area of the dwelling.

The dwelling_result that is returned should be applied to both the below-grade GLA as well as the above-grade GLA.

3.3 - Multi-Family Dwellings
section_3.3

Multi-family dwellings can be run simply by providing the following field in the search parameters:

  • multi_unit_count [integer]: Number of units on the property; this field defaults to '1' and can be excluded from a search if the intent is to calculate a single-family replacement cost estimate.

Note that while this is the only incremental field that needs to be provided with the search parameters, the inputs provided as part of Section 3.0 (single-family dwellings) will need to be adjusted to accurately reflect the totals across the property. For example, GLA and bath count variables should be provided in aggregate across all units on the property.

secton_3.4
3.4 - Example of Multi Family Site-Build Dwelling Request

These minimum required fields should be passed, with the appropriate checkfields credentials in a JSON file as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       "propnum": 0,

       "month": 1,

       "day": '1',

       "year": '2022',

       "address": "12345 Sample Avenue",

       "zip": "91355",

       "quality": 3.5,

       "gla": 6000,

       "bath_full": 6,

       "bath_half": 3,

       "stories": 2

       "multi-unit count": 3

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": null, 

      "basement_result": null, 

      "carport_result": null, 

      "covered_result": null, 

      "deck_result": null, 

      "dgarage_result": null, 

      "dwelling_result": 143.56575706428976, 

      "enclosed_result": null, 

      "garage_result": null, 

      "jobid_v3": <redacted>, 

      "pool_result": null, 

      "propnum": 0

    }

  ]

}

section_4.0

4.0 - Replacement Cost Estimates for Manufactured Homes {dwelling_result_mfg}

Properties may also be run with manufactured homes. To enable this feature, your search must include the following field:

  • manufactured_bin [binary]: pass as true to enable any of the features in this section; mark False or omit if search does not include any manufactured homes. Note: variable needs to be passed as a logical-encoded True value, and that if you pass any variables from this section but do not pass a True value for this variable, your response will not include any manufactured home outputs

Additionally, the following fields should also be passed with your search:

  • sections [integer]: The number of sections to build the manufactured home; ranges from '1' to '4'

  • gla_mfg [integer]: Gross living area of the manufactured home

  • bath_full_mfg [integer]: Number of full baths within the manufactured home

  • bath_half_mfg [integer]: Number of half baths within the manufactured home

  • mfg_qualid [integer]: The quality rating of the manufactured home, defined as follows:

    • For Basic quality, pass '1'

    • For Average quality, pass '​2'

    • For Above Average quality, pass '3'

    • For Good quality, pass '4'

    • For Very Good quality, pass '5'

    • For Best quality, pass '6'

  • airconditioning [integer]: Indication of air conditioning within the manufactured home; pass '1' for Central Air, otherwise pass '0'

  • climate [integer]: Indication of the manufactured home being equipped with a climate package, pass '1' for Yes, otherwise pass '0'

  • foundation_type [integer]: Indication of the manufactured home's foundation type, defined as follows:

    • For Permanent/Concrete quality, pass '1'

    • For Non-Permanent quality, pass '​2'

  • fireplaces [integer]: Number of fireplaces in the manufactured home

    • fireplace_type [integer]: Indication of the manufactured home's foundation type, defined as follows. Note: this field is required if fireplaces is nonzero; otherwise can be omitted:

      • For Built-In, pass '1'

      • For Freestanding, pass '​2'

  • mileage [integer]: The total approximate mileage from manufacturers. Delivery/Setup distance up to 100 miles is included.  Distance over 100 miles will result in an additional cost.

Note: if the property is being run without a dwelling (and only with a manufactured home), the fields described in Section 8.0 are also required.

4.1 - Example of Manufactured Homes Request
section_4.1

These minimum required fields should be passed, with the appropriate checkfields credentials in a JSON file as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       'propnum': '0',

       'month': '1',

       'day': '1',

       'year': '2022',

       'address': '12345 Sample Avenue',

       'zip': '91355',

       'manufactured_bin': true,

       'sections': '1',

       'gla_mfg': '1000',

       'mfg_qualid': '2',

       'bath_full_mfg': '2',

       'bath_half_mfg': '1',

       'airconditioning': '1',

       'climate': '1',

       'foundation_type': '2',

       'fireplaces': '1',

       'fireplace_type': '1',

       'mileage': '500'

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": null, 

      "basement_result": null, 

      "carport_result": null, 

      "covered_result": null, 

      "deck_result": null, 

      "dgarage_result": null, 

      "dwelling_result": null,

      "dwelling_result_mfg": 77.007087

      "enclosed_result": null, 

      "garage_result": null, 

      "jobid_v3": <redacted>, 

      "pool_result": null, 

      "propnum": 0

    }

  ]

}

section_5.0

5.0 - Requesting Additional Dwelling Components

With each property, you may also include a variety of additional components to fully develop the replacement cost estimates. This requires additional information for each component desired, though omit all fields for any additional components you do not wish to include with your search.

5.1 - Requesting a Built-In/Attached Garage Replacement Cost Estimate {garage_result}
section_5.1

The following fields should also be passed with your search:

  • garage_qualid [number]: The quality rating of the garage building materials on the DwellingCost scale from 1.0 to 8.0, with increments of 0.1 allowed

  • garage_gla [integer]: Square footage of the garage

  • garage_attached [integer]: Binary variable to distinguish attached garages from built-in garages: 1 = Attached Garage, 0 = Built-In Garage

5.2 - Requesting a Detached Garage Replacement Cost Estimate {dgarage_result}
section_5.2

The following fields should also be passed with your search:

  • dgarage_qualid [number]: The quality rating of the detached garage building materials on the DwellingCost scale from 1.0 to 8.0, with increments of 0.1 allowed

  • dgarage_gla [integer]: Square footage of the detached garage

5.3 - Requesting a Carport Replacement Cost Estimate {carport_result}
section_5.3

The following fields should also be passed with your search:

  • carport_qualid [number]: The quality rating of the carport building materials on the DwellingCost scale from 1.0 to 8.0, with increments of 0.1 allowed

  • carport_gla [integer]: Square footage of the carport

5.4 - Requesting a Attic Replacement Cost Estimate {attic_result}
section_5.4

The following fields should also be passed with your search:

  • attic_qualid [number]: The quality rating of the attic building materials on the DwellingCost scale from 1.0 to 8.0, with increments of 0.1 allowed

  • attic_gla [integer]: Square footage of the attic

5.5 - Requesting a Basement Replacement Cost Estimate {basement_result}
section_5.5

The following fields should also be passed with your search:

  • basement_qualid [number]: The quality rating of the basement building materials on the DwellingCost scale from 1.0 to 8.0, with increments of 0.1 allowed

  • basement_gla [integer]: Square footage of the basement

  • perc_Finished [integer]: Percentage of basement considered to be "finished." Note that the integer passed should reflect the whole number percentage of the intended value (e.g., '50' would indicate a basement is 50% finished)

5.6 - Example Additional Dwelling Component Request
section_5.6

If all components described in Section 5.0 were to be included in a search with a valid checkfields parameter, the request JSON file would read as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       'propnum': '0',

       'month': '1',

       'day': '1',

       'year': '2022',

       'address': '12345 Sample Avenue',

       'zip': '91355',

       'quality': '3.5',

       'gla': '2200',

       'bath_full': '2',

       'bath_half': '0',

       'stories': '2'

       "garage_qualid": "3.0",

       "garage_gla": "900",

       "garage_attached": "1",

       "dgarage_qualid": "3.0",

       "dgarage_gla": "700",

       "carport_qualid": "3.5",

       "carport_gla": "850",

       "basement_qualid": "4.0",

       "basement_gla": "2001",

       "perc_Finished": "33",

       "attic_gla": "1500",

       "attic_qualid": "2.5"

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": 17.333754190782923, 

      "basement_result": 52.5936006876664, 

      "carport_result": 28.58315056717126, 

      "covered_result": 35.33338884300715, 

      "deck_result": 14.671737408959647, 

      "dgarage_result": 47.26929592431724, 

      "dwelling_result": 149.73040267575863, 

      "enclosed_result": 43.8187798386767, 

      "garage_result": 52.402442706480635, 

      "jobid_v3": <redacted>, 

      "pool_result": 192.6588350880665, 

      "propnum": 0

    }

  ]

}

6.0 - Requesting Additional Structures

section_6.0

Properties may also be run with any combination of additional structures (i.e., guest houses, sheds, barns, workshops and bonus rooms). To enable this feature, your search must include the following field:

  • structures_bin [binary]: pass as true to enable any of the features in this section; mark False or omit if search does not include any additional structures. Note, variable needs to be passed as a logical-encoded True value, and if you pass any variables from this section but do not pass a True value for this variable, your response will not include any additional structure outputs

6.1 - Requesting an Accessory Dwelling Unit (ADU) / Guest House Replacement Cost Estimate {guest_result}
section_6.1

The following fields should also be passed with your request:

  • quality_guest [number]: The quality rating of the ADU building materials on the DwellingCost scale from 1.0 to 8.0, with increments of 0.1 allowed

  • gla_guest [integer]: Gross living area for the ADU

  • bath_full_guest [integer]: Number of full baths within the ADU

  • bath_half_guest [integer]: Number of half baths within the ADU

  • stories_guest [number]: Number of stories within the ADU (maximum of 4.0; increments of 0.5 allowed)

6.2 - Requesting a Shed Replacement Cost Estimate {shed_result}
section_6.2

The following fields are required to be passed with your request:

  • shed_qualid [integer]: The quality rating of the shed, defined as follows:

    • For Basic quality, pass '1'

    • For Average quality, pass '​2'

    • For Above Average quality, pass '3'

    • For Good quality, pass '4'

    • For Very Good quality, pass '5'

    • To have DwellingCost calculate the quality rating of the shed, pass '6'; NOTE: additional information about the shed is needed for this option to be enabled. See Section 6.6 below.

  • shed_sqft [number]: Square footage of the shed

  • shed_interiorfin [string]: Indication if the interior of the shed is finished. Pass 'Yes' or 'No'

    • shed_interiorperc [integer]: Percentage of shed interior that is finished; this field is required if shed_interiorfin is set to 'Yes'; otherwise can be set to 0 or omitted. Note that the integer passed should reflect the whole number percentage of the intended value (e.g., '50' would indicate a shed is 50% finished)

  • shed_electrical [string]: Indication if the shed is wired for electricity; may be a branch circuit of the main panel or have its own subpanel. Pass 'Yes' or 'No'

    • shed_subpanel [string]: Indication if shed has its own subpanel; this field is required if shed_electrical is set to 'Yes'; otherwise can be set to 'No Subpanel' or omitted. Pass 'With Subpanel' or 'No Subpanel'

  • shed_plumbing [string]: Indication if the shed has plumbing. Pass 'Yes' or 'No'

    • shed_plumbing_fixtures [number]: Number of plumbing fixtures in the shed; this field is required if shed_plumbing is set to 'Yes'; otherwise can be set to '0' or omitted.​​

6.3 - Requesting a Workshop Replacement Cost Estimate {workshop_result}
section_6.3

The following fields are required to be passed with your request:

  • workshop_qualid [integer]: The quality rating of the workshop, defined as follows:

    • For Basic quality, pass '1'

    • For Average quality, pass '​2'

    • For Above Average quality, pass '3'

    • For Good quality, pass '4'

    • For Very Good quality, pass '5'

    • To have DwellingCost calculate the quality rating of the workshop, pass '6'; NOTE: additional information about the workshop is needed for this option to be enabled. See Section 6.6 below.

  • workshop_sqft [number]: Square footage of the workshop

  • workshop_interiorfin [string]: Indication if the interior of the workshop is finished. Pass 'Yes' or 'No'

    • workshop_interiorperc [integer]: Percentage of workshop interior that is finished; this field is required if workshop_interiorfin is set to 'Yes'; otherwise can be set to 0 or omitted. Note that the integer passed should reflect the whole number percentage of the intended value (e.g., '50' would indicate a workshop is 50% finished)

  • workshop_electrical [string]: Indication if the workshop is wired for electricity; required to be 'Yes' by definition of a workshop

    • workshop_subpanel [string]: Indication if workshop has its own subpanel; Pass 'With Subpanel' or 'No Subpanel'

  • workshop_plumbing [string]: Indication if the workshop has plumbing. Pass 'Yes' or 'No'

    • workshop_plumbing_fixtures [number]: Number of plumbing fixtures in the workshop; this field is required if workshop_plumbing is set to 'Yes'; otherwise can be set to '0' or omitted.​​

6.4 - Requesting a Bonus Room Replacement Cost Estimate {bonus_result}
section_6.4

The following fields are required to be passed with your request:

  • bonus_qualid [integer]: The quality rating of the bonus room, defined as follows:

    • For Basic quality, pass '1'

    • For Average quality, pass '​2'

    • For Above Average quality, pass '3'

    • For Good quality, pass '4'

    • For Very Good quality, pass '5'

    • To have DwellingCost calculate the quality rating of the bonus room, pass '6'; NOTE: additional information about the bonus room is needed for this option to be enabled. See Section 6.6 below.

  • bonus_sqft [number]: Square footage of the bonus room

  • bonus_interiorfin [string]: Indication if the interior of the bonus room is finished; required to be 'Yes' by definition of a bonus room

    • bonus_interiorperc [integer]: Percentage of bonus room interior that is finished. Note that the integer passed should reflect the whole number percentage of the intended value (e.g., '100' would indicate a bonus room that is 100% finished)

  • bonus_electrical [string]: Indication if the bonus room is wired for electricity; required to be 'Yes' by definition of a bonus room

    • bonus_subpanel [string]: Indication if bonus room has its own subpanel; Pass 'With Subpanel' or 'No Subpanel'

  • bonus_plumbing [string]: Indication if the bonus room has plumbing. Pass 'Yes' or 'No'

    • bonus_plumbing_fixtures [number]: Number of plumbing fixtures in the bonus room; this field is required if bonus_plumbing is set to 'Yes'; otherwise can be set to '0' or omitted.​​

6.5 - Requesting a Barn Replacement Cost Estimate {barn_result}
section_6.5

The following fields are required to be passed with your request:

  • barn_pole_bin [string]: A pile foundation is defined as a series of columns constructed or inserted into the ground to transmit loads to a lower level of subsoil. A pile is a long cylinder made up of a strong material, such as concrete, wood, or metal. Piles transfer the loads from structures to hard strata, rocks, or soil with high bearing capacity. Pass 'Yes' or 'No'.

    • barn_walls_bin [string]: Indication if the pole barn has exterior walls; this field is required if barn_pole_bin is set to 'Yes', otherwise can be set to 'No' or omitted. Pass 'Yes' or 'No'.

  • barn_qualid [integer]: The quality rating of the barn, defined as follows:

    • For Basic quality, pass '1'

    • For Average quality, pass '​2'

    • For Above Average quality, pass '3'

    • For Good quality, pass '4'

    • For Very Good quality, pass '5'

    • To have DwellingCost calculate the quality rating of the barn, pass '6'; NOTE: additional information about the barn is needed for this option to be enabled. See Section 6.6 below.

  • barn_sqft [number]: Square footage of the barn

  • barn_interiorfin [string]: Indication if the interior of the barn is finished. Pass 'Yes' or 'No'

    • barn_interiorperc [integer]: Percentage of barn interior that is finished; this field is required if barn_interiorfin is set to 'Yes'; otherwise can be set to 0 or omitted. Note that the integer passed should reflect the whole number percentage of the intended value (e.g., '50' would indicate a barn is 50% finished)

  • barn_electrical [string]: Indication if the barn is wired for electricity; may be a branch circuit of the main panel or have its own subpanel. Pass 'Yes' or 'No'

    • barn_subpanel [string]: Indication if barn has its own subpanel; this field is required if barn_electrical is set to 'Yes'; otherwise can be set to 'No Subpanel' or omitted. Pass 'With Subpanel' or 'No Subpanel'

  • barn_plumbing [string]: Indication if the barn has plumbing. Pass 'Yes' or 'No'

    • barn_plumbing_fixtures [number]: Number of plumbing fixtures in the barn; this field is required if barn_plumbing is set to 'Yes'; otherwise can be set to '0' or omitted.​​

6.6 - Using DwellingCost to Calculate Additional Structure Quality Ratings
section_6.6

If the request indicates DwellingCost should calculate the quality of the structure (that is, {structure}_qualid is set to '6'), the following fields are required. If {structure}_qualid is not set to '6', these fields can be omitted from the request; however, if {structure}_qualid is set to '6' and these fields are omitted, the structure will run at Very Good quality. Note that for the fields below, '{structure}' should be replaced with either 'shed', 'workshop', 'bonus' or 'barn', as applicable; for examples, see the second provided example request in Section 6.7.

  • {structure}_footings_id [integer]: Whether or not the foundation has footings, defined as follows:

    • For Yes, pass '2'

    • For None, pass '​1'

  • {structure}_flooring_id [integer]: Indication of the type of flooring in the structure

    • ​For None / Existing, pass '1'​

    • For Asphalt, pass '​2'

    • For Wood, pass '3'

    • For Concrete, pass '4'

  • {structure}_extwall_id [integer]: Indication of the type of exterior wall in the structure

    • ​For Metal, pass '1'​

    • For Wood, pass '​2'

    • For Block / Brick, pass '3'

  • {structure}_wallheight_id [integer]: Indication of the wall height in the structure

    • ​For Standard (< 12'), pass '1'​

    • For High (12' - 16'), pass '​2'

    • For Very High (> 16'), pass '3'

  • {structure}_rooftype_id [integer]: Indication of the roof type of the structure

    • ​For Comp, Wood, Poly (corrugated plastic) / Low, pass '1'​

    • For Comp, Wood, Poly (corrugated plastic) / High, pass '​2'

    • For Metal, Tile / Low, pass '3'

    • For Metal, Tile / High, pass '4'

Note: This feature is not available for Additional Dwelling Units (ADUs) / Guest Houses.

section_6.7
6.7 - Additional Structures Example

If all components described in Section 6.0 were to be included in a search with a valid checkfields parameter, without using DwellingCost to calculate quality ratings (that is, not utilizing the feature described in Section 6.6), the request JSON file would read as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       'propnum': '0',

       'month': '1',

       'day': '1',

       'year': '2022',

       'address': '12345 Sample Avenue',

       'zip': '91355',

       'quality': '3.5',

       'gla': '2200',

       'bath_full': '2',

       'bath_half': '0',

       'stories': '2'

       'quality_guest': '3.0',

       'bath_full_guest': '2',

       'bath_half_guest': '1',

       'stories_guest': '2',

       'gla_guest': '900',

       'structures_bin': true,

       'shed_qualid': '3',

       'shed_sqft': '750',

       'shed_interiorfin': 'Yes',

       'shed_interiorperc': '33',

       'shed_electrical': 'Yes',

       'shed_subpanel': 'With Subpanel',

       'shed_plumbing': 'Yes',

       'shed_plumbing_fixtures': '2',

       'workshop_qualid': '4',

       'workshop_sqft': '750',

       'workshop_interiorfin': 'Yes',

       'workshop_interiorperc': '100',

       'workshop_electrical': 'Yes',

       'workshop_subpanel': 'With Subpanel',

       'workshop_plumbing': 'Yes',

       'bonus_qualid': '2',

       'bonus_sqft': '600',

       'bonus_interiorfin': 'Yes',

       'bonus_interiorperc': '100',

       'bonus_electrical': 'Yes',

       'bonus_subpanel': 'No Subpanel',

       'bonus_plumbing': 'Yes',

       'bonus_plumbing_fixtures': '3',

       'barn_pole_bin': 'Yes',

       'barn_walls_bin': 'Yes',

       'barn_qualid': '3',

       'barn_sqft': '850',

       'barn_interiorfin': 'Yes',

       'barn_interiorperc': '25',

       'barn_electrical': 'Yes',

       'barn_subpanel': 'No Subpanel',

       'barn_plumbing': 'No',

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": 17.333754190782923, 

      "barn_result": 90.5221092180189,

      "basement_result": 52.5936006876664,

      "bonus_result": 124.95493270507974, 

      "carport_result": 28.58315056717126, 

      "covered_result": 35.33338884300715, 

      "deck_result": 14.671737408959647, 

      "dgarage_result": 47.26929592431724, 

      "dwelling_result": 149.73040267575863, 

      "enclosed_result": 43.8187798386767, 

      "garage_result": 52.402442706480635, 

      "guest_result": 158.5338564226951,

      "jobid_v3": <redacted>, 

      "pool_result": 192.6588350880665, 

      "propnum": 0

      "shed_result": 36.55897426553757,

      "workshop_result": 97.13616341968535

    }

  ]

}

If all components described in Section 6.0 were to be included in a search and all additional structures were utilizing DwellingCost to calculate the quality rating (that is, Section 6.6 is being followed for all additional structures provided), the request JSON file would read as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       'propnum': '0',

       'month': '1',

       'day': '1',

       'year': '2022',

       'address': '12345 Sample Avenue',

       'zip': '91355',

       'quality': '3.5',

       'gla': '2200',

       'bath_full': '2',

       'bath_half': '0',

       'stories': '2'

       'quality_guest': '3.0',

       'bath_full_guest': '2',

       'bath_half_guest': '1',

       'stories_guest': '2',

       'gla_guest': '900',

       'structures_bin': true,

       'shed_qualid': '6',

       'shed_sqft': '750',

       'shed_interiorfin': 'Yes',

       'shed_interiorperc': '33',

       'shed_electrical': 'Yes',

       'shed_subpanel': 'With Subpanel',

       'shed_plumbing': 'Yes',

       'shed_plumbing_fixtures': '2',

       'shed_footings_id': '2',

       'shed_flooring_id': '3',

       'shed_extwall_id': '2',

       'shed_wallheight_id': '2',

       'shed_rooftype_id': '3',

       'workshop_qualid': '6',

       'workshop_sqft': '750',

       'workshop_interiorfin': 'Yes',

       'workshop_interiorperc': '100',

       'workshop_electrical': 'Yes',

       'workshop_subpanel': 'With Subpanel',

       'workshop_plumbing': 'Yes',

       'workshop_footings_id': '1',

       'workshop_flooring_id': '1',

       'workshop_extwall_id': '1',

       'workshop_wallheight_id': '1',

       'workshop_rooftype_id': '1',

       'bonus_qualid': '6',

       'bonus_sqft': '600',

       'bonus_interiorfin': 'Yes',

       'bonus_interiorperc': '100',

       'bonus_electrical': 'Yes',

       'bonus_subpanel': 'No Subpanel',

       'bonus_plumbing': 'Yes',

       'bonus_plumbing_fixtures': '3',

       'bonus_footings_id': '1',

       'bonus_flooring_id': '2',

       'bonus_extwall_id': '1',

       'bonus_wallheight_id': '2',

       'bonus_rooftype_id': '3',

       'barn_pole_bin': 'Yes',

       'barn_walls_bin': 'Yes',

       'barn_qualid': '6',

       'barn_sqft': '850',

       'barn_interiorfin': 'Yes',

       'barn_interiorperc': '25',

       'barn_electrical': 'Yes',

       'barn_subpanel': 'No Subpanel',

       'barn_plumbing': 'No',

       'barn_footings_id': '1',

       'barn_flooring_id': '1',

       'barn_extwall_id': '1',

       'barn_wallheight_id': '1',

       'barn_rooftype_id': '2'

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": 17.333754190782923, 

      "barn_result": 67.05950711069073,

      "basement_result": 52.5936006876664,

      "bonus_result": 190.030319018335, 

      "carport_result": 28.58315056717126, 

      "covered_result": 35.33338884300715, 

      "deck_result": 14.671737408959647, 

      "dgarage_result": 47.26929592431724, 

      "dwelling_result": 149.73040267575863, 

      "enclosed_result": 43.8187798386767, 

      "garage_result": 52.402442706480635, 

      "guest_result": 158.5338564226951,

      "jobid_v3": <redacted>, 

      "pool_result": 192.6588350880665, 

      "propnum": 0

      "shed_result": 39.788326927033545,

      "workshop_result": 62.82274296631838

    }

  ]

}

section_7.0

7.0 - Requesting Additional Dwelling Components

7.1 - Requesting a Deck Replacement Cost Estimate {deck_result}
section_7.1

The following fields should also be passed with your search:

  • deck_qual [integer]: The quality rating of the deck building materials, defined as follows:

    • ​​For Standard, pass '1'​

    • For Above Average, pass '​2'

    • For Good, pass '3'

    • For Excellent, pass '4'

  • deck_sqft [integer]: Square footage of the deck

7.2 - Requesting a Covered Patio Replacement Cost Estimate {covered_result}
section_7.2

The following fields should also be passed with your search:

  • covered_qual [integer]: The quality rating of the covered patio building materials, defined as follows:

    • ​​​For Standard, pass '1'​

    • For Above Average, pass '​2'

    • For Good, pass '3'

    • For Excellent, pass '4'

  • covered_sqft [integer]: Square footage of the covered patio

7.3 - Requesting a Enclosed Patio Replacement Cost Estimate {enclosed_result}
section_7.3

The following fields should also be passed with your search:

  • enclosed_qual [number]: The quality rating of the enclosed patio building materials, defined as follows:

    • ​​​For Standard, pass '1'​

    • For Above Average, pass '​2'

    • For Good, pass '3'

    • For Excellent, pass '4'

  • enclosed_sqft [integer]: Square footage of the enclosed patio

  • enclosed_linft [integer]: Total linear feet of the non-dwelling wall of an enclosed patio

7.4 - Requesting a Pool Replacement Cost Estimate {pool_result}
section_7.4

The following fields should also be passed with your search:

  • pool_qual [integer]: The quality rating of the pool's building materials, defined as follows:

    • ​​​For Low Cost Pool, pass '1'​

    • For Shallow Pool, pass '​2'

    • For Standard, pass '3'

    • For Above Average, pass '4'

    • For Good, pass '5'

    • For Excellent, pass '6'

  • pool_sqft [integer]: Square footage of the pool

7.5 - Example Site Improvement Request
section_7.5

If all of the above components we're passed as a request, the JSON body, including the appropriate checkfields would print as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       "propnum": "0",

       "month": "1",

       "day": "1",

       "year": "2022",

       "address": "12345 Sample Avenue",

       "zip": "91355",

       "quality": "3.5",

       "gla": "2200",

       "bath_full": "2",

       "bath_half": "0",

       "stories": "2"

       "garage_qualid": "3.0",

       "garage_gla": "900",

       "garage_attached": "1",

       "dgarage_qualid": "3.0",

       "dgarage_gla": "700",

       "carport_qualid": "3.5",

       "carport_gla": "850",

       "basement_qualid": "4.0",

       "basement_gla": "2001",

       "perc_Finished": "33",

       "attic_gla": "1500",

       "attic_qualid": "2.5",

       "deck_qual": "3",

       "deck_sqft": "700",

       "covered_qual": "3",

       "covered_sqft": "850",

       "enclosed_qual": "3",

       "enclosed_linft": "120",

       "enclosed_sqft": "600",

       "pool_qual": "4",

       "pool_sqft": "650"}]}

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": 17.333754190782923, 

      "basement_result": 52.5936006876664, 

      "carport_result": 28.58315056717126, 

      "covered_result": 35.33338884300715, 

      "deck_result": 14.671737408959647, 

      "dgarage_result": 47.26929592431724, 

      "dwelling_result": 149.73040267575863, 

      "enclosed_result": 43.8187798386767, 

      "garage_result": 52.402442706480635, 

      "jobid_v3": <redacted>, 

      "pool_result": 192.6588350880665, 

      "propnum": 0

    }

  ]

}

section_8.0

8.0 - Requesting Ad Hoc Elements

All replacement cost elements can be run as part of a large property search or ad hoc as needed. If a dwelling component, site improvement, or additional structure are run without an accompanying dwelling or manufactured home, the following fields become required in addition to any fields detailed in that component's documentation above:

  • propnum [integer]: An integer (should begin at 0) used to identify individual properties in a batch request

  • year [integer]: The effective year of the replacement cost estimate; format yyyy

  • month [integer]: The effective month of the replacement cost estimate; format m

  • day [integer]: The effective day of the replacement cost estimate; format d

  • address [string]: Reflects property address; maximum 255 characters

  • zip [string]: Five character zip code as recognized by USPS (note: you must include any leading or trailing zeroes to get an accurate result)

8.1 - Example Ad Hoc Barn Request
section_8.1

As an example, if a barn cost estimate was required without a corresponding dwelling or manufactured home, the request would be constructed as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       'propnum': '0',

       'month': '1',

       'day': '1',

       'year': '2022',

       'address': '12345 Sample Avenue',

       'zip': '91355',

       'barn_pole_bin': 'Yes',

       'barn_walls_bin': 'Yes',

       'barn_qualid': '3',

       'barn_sqft': '850',

       'barn_interiorfin': 'Yes',

       'barn_interiorperc': '25',

       'barn_electrical': 'Yes',

       'barn_subpanel': 'No Subpanel',

       'barn_plumbing': 'No',

     }]

}

This search would return a HTTP <Response [200]>, with a JSON body such as:

{

  "Result": [

    {

      "attic_result": null, 

      "barn_result": 90.5221092180189,

      "basement_result": null,

      "bonus_result": null, 

      "carport_result": null, 

      "covered_result": null, 

      "deck_result": null, 

      "dgarage_result": null, 

      "dwelling_result": null, 

      "enclosed_result": null, 

      "garage_result": null, 

      "guest_result": null,

      "jobid_v3": <redacted>, 

      "pool_result": null, 

      "propnum": 0

      "shed_result": null,

      "workshop_result": null

    }

  ]

}

section_9.0

9.0 - Generating DwellingCost.com Reports for Property Searches (with PDF Downloads)

Method: GET

Endpoint: https://dwellingcost.com/

DwellingCost allows for the creation of DwellingCost formatted reports for all searches run via API.  You can generate a report for any searches performed via your credentials by building a URL from the above endpoint, with the following parameters. To enable this feature, please reach out to your DwellingCost representative:

  • report_key [string]: Your unique account-level report key which can be found in your DwellingCost Web Services Portal

  • jobid_v3 [string]: The jobid returned with any property search

  • propnum [integer]: The property number reflecting the specific property the report should be generated for (reports can only be created for one property at a time in a search; however, you can build links for all properties (i.e., all unique propnums) in a search and allow users to click through to them)

Users can then generate PDF reports by clicking "Download PDF" at the top of each report; report URLs last until 11:45pm (Pacific Standard Time) of the same day that the search was run.

9.1 - Report Annotations (Does Not Impact Cost Estimates)
section_9.1

When running a property request, you may provide the following fields from the end user to enhance the report with annotations. These fields have no impact on the cost estimate values and are purely to provide support behind quality ratings and other assumptions made in the report.

  • millwork [integer]: Indication of higher quality millwork; pass '1' for 'Yes', otherwise omit

  • flooring [integer]: Indication of higher quality flooring; pass '1' for 'Yes', otherwise omit

  • counters [integer]: Indication of higher quality counters; pass '1' for 'Yes', otherwise omit

  • cabinetry [integer]: Indication of upgraded cabinetry; pass '1' for 'Yes', otherwise omit

  • appliances [integer]: Indication of higher quality appliances; pass '1' for 'Yes', otherwise omit

  • pfixtures [integer]: Indication of upgraded plumbing fixtures; pass '1' for 'Yes', otherwise omit

  • efixtures [integer]: Indication of upgraded electrical fixtures; pass '1' for 'Yes', otherwise omit

  • doors [integer]: Indication of higher quality doors; pass '1' for 'Yes', otherwise omit

  • windows [integer]: Indication of higher quality windows and fenestration; pass '1' for 'Yes', otherwise omit

  • accents [integer]: Indication of higher quality exterior finish, accents and ornamentation; pass '1' for 'Yes', otherwise omit

  • hvac [integer]: Indication of a high-efficiency HVAC system; pass '1' for 'Yes', otherwise omit

  • solar [integer]: Indication of a solar electrical system; pass '1' for 'Yes', otherwise omit

  • framing [integer]: Indication of high quality framing; pass '1' for 'Yes', otherwise omit

  • foundation [integer]: Indication of higher quality foundation; pass '1' for 'Yes', otherwise omit

Furthermore, comments can be provided from the report itself.

9.2 - Example of Dwelling Request with Annotations

An example with annotation fields, with the appropriate checkfields credentials, in a JSON file as follows:

{

"checkfields":

     [{

       "account": "123456789abcdefghijklmnopqrstuvwxyz",

       "secret": "zyxwvutsrqponmlkjihgfedcba987654321"

     }],

"Request":

     [{

       'propnum': '0',

       'month': '1',

       'day': '1',

       'year': '2022',

       'address': '12345 Sample Avenue',

       'zip': '91355',

       'quality': '3.5',

       'gla': '2200',

       'bath_full': '2',

       'bath_half': '0',

       'stories': '2',

       'millwork': '1',

       'flooring': '1',

       'cabinetry': '1',

       'windows': '1',

     }]

}

section_9.2
bottom of page