House

This walkthrough demonstrates how a client creates a house goal and how house API enables this functionality.

First the information that the client needs to input is the location of the house.

We can see all the available locations in API Library by using this API:

GET /api/generalCalculator/v2/houses/regions?country=USA

We can see that this API accepts country as a query parameter. Here is the response of that request:

[
  ...
  {
    "name": "California",
    "cities": [
      ...
      {
      "name": "San Francisco",
      "districts": []
      },
      ...
    ]
  },
  ...
]

Next we need to input the house type and the down payment percentage. They are required parameters of goal amount calculator API.

We can see all the available house types in API Library by using this API:

GET /api/generalCalculator/v2/houses/types?country=USA&city=San Francisco

We can see that this API accepts country and city as query parameters. Here is the response of that request:

[
  "One Bed",
  "Two Bed",
  "Three Bed",
  "Four Bed",
  "More than Four Bed",
  "single family",
  "Condo"
]

We now have all the necessary information to calculate the house cost. This is the API to do that:

POST /api/generalCalculator/v2/goalCalculator/calcHouseGoalAmount

With a JSON payload containing the client’s data inputted from the previous steps:

{
  "downPaymentYear": 2026,
  "country": "USA",
  "region": "California",
  "city": "San Francisco",
  "houseType": "More than Four Bed",
  "downPaymentPct": 0.2,
  "inflationRate": 0.05, // (the library has an API to get this)
  "currentYear": 2021
}

And here is the response

{
  "yearsToGoal": 5,
  "houseCostInflationAdj": 2601317.08,
  "currency": "USD",
  "downPaymentAmt": 520263.41
}

We can then display the house goal amount needed and other house information as shown below.