DwellingCost.com Application Programming Interface (API) v3.0.1
Endpoint Shortcuts
This documentation supports DwellingCost.com's Application Programming Interface (API) for its Appraiser Replacement Cost Estimator Product, version 3.0.0. 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 HTTP (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 base URL has been provided in your Web Services portal, and using that base URL there are two endpoints to connect to.
Authenticating with the DwellingCost API
DwellingCost's API utilizes a two-step OAuth2.0 authentication engine which for efficiency and security is fully authenticated at the server plane. As such, authenticating with the DwellingCost API has been streamlined in v3 to be passed in the body of 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"
}]
}
/dcrequests - Replacement Cost Estimates for Stick-Built Dwellings {dwelling_result}
Method: GET, POST
Endpoint: https://<url_in_web_services_portal>/dcrequests
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') There can be up to 30 property records in the Request parameter, with the following required fields:
-
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)
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": "2020",
"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
}
]
}
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.
Requesting a Built-In/Attached Garage Replacement Cost Estimate {garage_result}
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
Requesting a Detached Garage Replacement Cost Estimate {dgarage_result}
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
Requesting a Carport Replacement Cost Estimate {carport_result}
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
Requesting a Attic Replacement Cost Estimate {carport_result}
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
Requesting a Basement Replacement Cost Estimate {basement_result}
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)
Requesting a Deck Replacement Cost Estimate {deck_result}
The following fields should also be passed with your search:
-
deck_qualid [integer]: The quality rating of the deck building materials on the DwellingCost scale from 1 through 4
-
deck_sqft [integer]: Square footage of the deck
Requesting a Covered Patio Replacement Cost Estimate {covered_result}
The following fields should also be passed with your search:
-
covered_qualid [integer]: The quality rating of the covered patio building materials on the DwellingCost scale from 1 through 4
-
covered_sqft [integer]: Square footage of the covered patio
Requesting a Enclosed Patio Replacement Cost Estimate {enclosed_result}
The following fields should also be passed with your search:
-
enclosed_qualid [number]: The quality rating of the enclosed patio building materials on the DwellingCost scale from 1 through 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
Requesting a Pool Replacement Cost Estimate {pool_result}
The following fields should also be passed with your search:
-
pool_qualid [integer]: The quality rating of the pool's building materials on the DwellingCost scale from 1 through 6
-
pool_sqft [integer]: Square footage of the pool
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": "2020",
"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
}
]
}
/dcmfgrequests - Replacement Cost Estimates for Manufactured Homes {dwelling_result}
Method: GET, POST
Endpoint: https://<url_in_web_services_portal>/dcmfgrequests
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 be otherwise be observed within that string (for instance, an integer to represent the month of January should be passed as string '1') There can be up to 30 property records in the Request parameter, with the following required fields:
-
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_mfg [string]: Five character zip code as recognized by USPS (note: you must include any leading or trailing zeroes to get an accurate result)
-
quality_mfg_q3 [integer]: The quality of the dwelling. Pass '1' for Basic quality; '2' for Average quality; '3' for Above Average quality; '4' for Good quality. For any quality above Good (Very Good and Best), we recommend using the Stick-Built endpoint (/dcrequests) and pass a quality level of '1.4' for Very Good (Modular) quality and '2.4' for Best (Modular) quality
-
livingarea_mfg [integer]: Gross living area for the dwelling
-
bath_full_mfg [integer]: Number of full baths within the dwelling
-
bath_half_mfg [integer]: Number of half baths within the dwelling
-
fireplaces [integer]: Number of fireplaces
-
fireplaces_type_v3 [integer]: Pass '1' for Built-In; '2' for Freestanding
-
foundation_type_v3 [integer]: Pass '1' for Permanent/Concrete; '2' for Non-Permanent
-
climate_v3 [integer]: Pass '0' for No Climate Package; '1' for the Climate Package
-
airconditioning_v3 [integer]: Pass '0' for No A/C; '1' for Central Air
-
mileage [number]: Delivery mileage from manufacturer to site; Up to 100 miles is included (you may either omit in request or pass the actual mileage amount)
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": "2020",
"address": "12345 Sample Avenue",
"zip_mfg": "91355",
"quality_mfg_v3": "3",
"livingarea_mfg": "2200",
"sections": "1",
"bath_full_mfg": "2",
"bath_half_mfg": "0",
"fireplace_type_v3": "1",
"fireplaces": "2",
"foundation_type_v3": "2",
"climate_v3": "1",
"airconditioning_v3": "1",
"mileage": "120"
}]
}
This search would return a HTTP <Response [200]>, with a JSON body such as:
{
"Result": [
{
"basement_result": null,
"carport_result": null,
"dwelling_result": 43.712339966593916,
"garage_result": null,
"jobid_v3": <redacted>,
"propnum": 0
}
]
}
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.
Requesting a Garage Replacement Cost Estimate {garage_result}
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
Requesting a Carport Replacement Cost Estimate {carport_result}
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
Requesting a Basement Replacement Cost Estimate {basement_result}
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)
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": "2020",
"address": "12345 Sample Avenue",
"zip_mfg": "91355",
"quality_mfg_v3": "3",
"livingarea_mfg": "2200",
"sections": "2",
"bath_full_mfg": "2",
"bath_half_mfg": "0",
"fireplace_type_v3": "1",
"fireplaces": "2",
"foundation_type_v3": "2",
"climate_v3": "1",
"airconditioning_v3": "1",
"mileage": "120"
"garage_quality": "3.0",
"garage_gla": "700",
"carport_qualid": "3.5",
"carport_gla": "850",
"basement_qualid": "4.0",
"basement_gla": "2001",
"perc_Finished": "33"
}]
}
This search would return a HTTP <Response [200]>, with a JSON body such as:
{
"Result": [
{
"basement_result": 52.59360068766641,
"carport_result": 28.58315056717126,
"dwelling_result": 43.712339966593916,
"garage_result": 52.402442706480635,
"jobid_v3": <redacted>,
"propnum": 0
}
]
}