Contents
Developers
Good Investment API
The API returns the Appreciation Rank for a US home with its confidence, the expected yearly appreciation of the home and its market, the monthly cost to own and the asking price against an estimated value. Read one home per call, or send a list to help decide which homes to buy or sell.
For an area, send a ZIP code. You get its appreciation over one year, five years and since 2000, the same figures for each of its neighborhoods at 0.7 km² resolution, and an estimate for the year in progress.
A test key reads 10 sample homes and never bills, so you can build the whole integration before you choose a plan.
Sign in or create a free account, and the key page opens.
- Base URL
- https://api.goodinvestment.io
- Format
- JSON over HTTPS, with a Bearer key
- Endpoints
- POST
/v1/properties/readPOST/v1/lists/rankGET/v1/zips/{zip}/appreciationGET/v1/usage
Getting started
Quickstart
- 1Create a test key on the API keys page.
- 2Put it in your shell as
export GI_TEST_KEY=gi_test_... - 3Send the request beside this step in cURL, Node or Python. It reads the first sample home.
A test key returns "livemode": false and "reads_billed": 0. The same call with a live key reads a real home and bills against your plan.
curl https://api.goodinvestment.io/v1/properties/read \
-H "Authorization: Bearer $GI_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"line1": "101 Sample Ridge Dr",
"city": "Austin",
"state": "TX",
"zip": "78704"
},
"asking_price": 689000
}'{
"as_of": "2026-11-14",
"external_id": null,
"address": {
"line1": "101 Sample Ridge Dr",
"city": "Austin",
"state": "TX",
"zip": "78704"
},
"price_used": {"amount": 689000.0, "source": "asking_price"},
"appreciation_rank": {
"status": "scored",
"score": 8.4,
"local_percentile": 84,
"band": "Top tier",
"confidence": "High"
},
"selection_rank": {"status": "scored", "local_percentile": 79},
"cost_to_own": {
"status": "ready",
"rate_percent": 6.24,
"rate_source": "freddie_mac_pmms",
"rate_as_of": "2026-11-12",
"down_payment_percent": 20.0,
"term_months": 360,
"loan_amount": 551200.0,
"principal_and_interest": 3390.25,
"property_tax": 1041.71,
"property_tax_rate_percent": 1.8143,
"property_tax_basis": "zip",
"insurance": 241.15,
"hoa": 0.0,
"mortgage_insurance": 0.0,
"total": 4673.11,
"includes_hoa": true
},
"price_vs_value": {
"status": "ready",
"asking_price": 689000.0,
"estimated_value": 702000,
"estimated_value_low": 661000,
"estimated_value_high": 744000,
"estimate_source": "third_party_avm",
"estimate_as_of": "2026-11-10",
"difference_percent": -1.9,
"flag": "near_value"
},
"market": {
"zip": "78704",
"county": "Travis",
"state": "TX",
"index_basis": "zip",
"recent_appreciation": {
"percent_per_year": 1.9,
"from_year": 2020,
"to_year": 2025
},
"long_run_appreciation": {
"percent_per_year": 5.8,
"from_year": 2000,
"to_year": 2025
},
"property_tax_rate_percent": 1.8143
},
"expected_appreciation": {
"status": "ready",
"market_percent_per_year": 5.8,
"home_percent_per_year": 12.56,
"edge_percent_per_year": 6.76,
"home_low_percent_per_year": -0.01,
"home_high_percent_per_year": 31.5,
"market_window": "long_run",
"from_year": 2000,
"to_year": 2025
},
"read_id": "rd_example01",
"reads_billed": 0,
"livemode": false
}Getting started
Authentication
Create and revoke keys on the API keys page. We show each key once, when you create it. Send it as Authorization: Bearer <key> from your own servers, never from a browser or an app.
gi_test_ | The sample homes | Never |
|---|---|---|
gi_live_ | Real US homes | Against your plan; live keys open on a paid plan |
Getting started
Sample homes
The sample homes are made up. Their addresses, values and ranks describe no real home, and the market figures for their ZIP codes are samples too. A test key finds a sample home by its address, or by its coordinates in attributes and list rows. sbx_10 comes back not_scored, so your integration can handle a home without a rank.
| sbx_01 | 101 Sample Ridge Dr, Austin, TX 78704 | 30.24512, -97.76831 | 1,610 | $689,000 |
|---|---|---|---|---|
| sbx_02 | 214 Example Hollow Ln, Austin, TX 78704 | 30.24187, -97.77412 | 2,245 | $915,000 |
| sbx_03 | 38 Demo Creek Ct, Austin, TX 78704 | 30.23842, -97.78106 | 1,380 | $575,000 |
| sbx_04 | 1407 Placeholder Ave, Austin, TX 78704 | 30.24955, -97.76248 | 742 | $329,000 |
| sbx_05 | 902 Specimen St, Austin, TX 78704 | 30.23411, -97.77593 | 1,495 | $612,000 |
| sbx_06 | 55 Trial Oak Blvd, Austin, TX 78704 | 30.25218, -97.77904 | 3,120 | $1,395,000 |
| sbx_07 | 77 Sample Terrace Rd, Columbus, OH 43206 | 39.94127, -82.98315 | 1,340 | $289,000 |
| sbx_08 | 610 Example Park Dr, Columbus, OH 43206 | 39.93802, -82.97721 | 1,885 | $365,000 |
| sbx_09 | 23 Demo Mill Way, Columbus, OH 43206 | 39.94466, -82.98904 | 1,104 | $239,000 |
| sbx_10 | 1180 Test Harbor Ln, Columbus, OH 43206 | 39.93514, -82.99237 | 1,520 | $312,000 |
On the ZIP endpoint a test key reads the sample ZIP codes 43206 and 78704. Their hexes are real cells around the sample homes, and every figure is made up.
Getting started
Idempotent requests
Every POST takes an Idempotency-Key header of up to 200 characters. On a live key, a repeat with the same key and the same body within 24 hours returns the first response with "reads_billed": 0 and X-Reads-Billed: 0, and the first call stays billed once. The same key with a different body returns a 422. Test keys bill nothing, so they answer every repeat afresh.
API reference
Read a property
https://api.goodinvestment.io/v1/properties/readSend an address and we look the home up, or send the home's details and we read it as you give it. Each home we rank is 1 read.
address, and optionallyasking_price- We do
- Fetch the property record and a value estimate from our data provider. A repeat lookup of an address inside 30 days comes from our cache.
- Bills
- 1 read
addressandattributeswith at leastlatitude,longitudeandsqft, plusasking_priceorestimated_value- We do
- Read the home as you describe it, with no lookup.
price_vs_valuefills in when you sendestimated_value; otherwise its status isno_estimate_supplied. - Bills
- 1 read
With no asking_price, the home is ranked at its estimated value and price_used.source says so. A home we cannot rank returns appreciation_rank.status: "not_scored" with every rank field null, and the call bills nothing.
Expected appreciation
expected_appreciation gives two yearly rates. market_percent_per_year is the long-run appreciation of the home's area. home_percent_per_year adds the edge for the home's rank: the average amount by which homes ranked like it beat or trailed their own market in historical tests. Single homes vary around that average, and home_low_percent_per_year to home_high_percent_per_year is the range from the 10th to the 90th percentile. A home without a rank still gets its market's rate, with status market_only.
Headers
AuthorizationstringrequiredBearer gi_test_...orBearer gi_live_...Idempotency-KeystringUp to 200 characters. A repeat with the same body inside 24 hours bills nothing.
Body params
addressobjectrequiredShowHide 4 fields in address
line1stringrequiredStreet number and name
citystringrequiredstatestringrequiredTwo-letter state code.
zipstringrequired5-digit ZIP code; ZIP+4 is accepted and cut to 5 digits.
asking_pricenumberThe list price or your offer. Without it the home is ranked at its estimated value.
attributesobjectThe home's details. Send them and we read the home as given, with no lookup.
ShowHide 9 fields in attributes
latitudenumberrequiredlongitudenumberrequiredsqftnumberrequiredLiving area in square feet.
property_typestringbedsnumberbathsnumberyear_builtintegerlot_sqftnumberhoa_monthlynumberMonthly HOA dues. Sent as 0 when there is none; left out when unknown.
estimated_valuenumber or objectYour own value estimate, as a number or an object with value, low, high and as_of.
ShowHide 4 fields in estimated_value
valuenumberrequiredlownumberhighnumberas_ofstringThe date your estimate was made.
financingobjectThe loan terms that price
cost_to_own.ShowHide 4 fields in financing
down_payment_percentnumberDefaults to20term_monthsintegerDefaults to360180 prices at the 15-year rate; any other term at the 30-year rate.
rate_percentnumberYour mortgage rate. Without it we use Freddie Mac's latest weekly average.
insurance_annualnumberWithout it
external_idstringYour own id
Response
read_idstringrequiredStarts rd_.
reads_billednumberrequiredOne of
01as_ofstringrequiredlivemodebooleanrequiredFalse for a test key.
external_idstringaddressobjectShowHide 4 fields in address
line1stringrequiredStreet number and name
citystringrequiredstatestringrequiredTwo-letter state code.
zipstringrequired5-digit ZIP code; ZIP+4 is accepted and cut to 5 digits.
price_usedobjectShowHide 2 fields in price_used
amountnumbersourcestringOne of
asking_priceestimated_value
appreciation_rankobjectrequiredWhere the home ranks for appreciation potential among homes in its own local market.
scoreis 0 to 10 andlocal_percentile0 to 100.confidenceis present wheneverscoreis, and a display of the score must show it: High when the home's own market has enough homes to rank against, Medium when it is ranked against a broader reference.ShowHide 5 fields in appreciation_rank
statusstringrequiredOne of
scorednot_scoredscorenumberrequiredlocal_percentileintegerrequiredbandstringrequired8 and up Top tier, 7 Strong, 5.5 Above average, 4 Around the median, below that Below the median.
One of
Top tierStrongAbove averageAround the medianBelow the medianconfidencestringrequiredOne of
HighMedium
selection_rankobjectrequiredA second, separate rank of the home within its local market, used to break ties when a list is ordered. It is never combined with the Appreciation Rank.
ShowHide 2 fields in selection_rank
statusstringrequiredOne of
scorednot_scoredlocal_percentileintegerrequired
cost_to_ownobjectrequiredMonthly cost in dollars, matching the Good Investment app to the cent. Principal and interest, property tax, insurance, mortgage insurance (below 20% down) and HOA when known. With no mortgage rate available the status is
rate_unavailableand every amount is null; no stand-in rate prices the answer.ShowHide 16 fields in cost_to_own
statusstringrequiredOne of
readyrate_unavailableno_pricerate_percentnumberrate_sourcestringOne of
freddie_mac_pmmssuppliedrate_as_ofstringdown_payment_percentnumberterm_monthsintegerloan_amountnumberprincipal_and_interestnumberproperty_taxnumberproperty_tax_rate_percentnumberproperty_tax_basisstringzip: the county effective rate for the home's ZIP. national_default: 0.88% a year where we have no rate for the ZIP.
One of
zipnational_defaultinsurancenumberhoanumbermortgage_insurancenumbertotalnumberincludes_hoabooleanFalse when HOA dues are unknown
price_vs_valueobjectrequiredShowHide 9 fields in price_vs_value
statusstringrequiredOne of
readyno_estimate_suppliedestimate_unavailableno_asking_priceasking_pricenumberestimated_valuenumberestimated_value_lownumberestimated_value_highnumberestimate_sourcestringthird_party_avm: an automated valuation from our data provider, fetched on estimate_as_of. supplied: the value you sent.
One of
third_party_avmsuppliedestimate_as_ofstringdifference_percentnumberAsking price against the estimate
flagstringAgainst the estimate's low-to-high range; null when the estimate has no range.
One of
below_valuenear_valueabove_value
marketobjectrequiredHouse price index history for the home's area, and its property tax rate.
ShowHide 7 fields in market
zipstringcountystringstatestringindex_basisstringThe narrowest area with a published house price index here.
One of
zipcountystaterecent_appreciationobjectShowHide 3 fields in recent_appreciation
percent_per_yearnumberfrom_yearintegerto_yearinteger
long_run_appreciationobjectShowHide 3 fields in long_run_appreciation
percent_per_yearnumberfrom_yearintegerto_yearinteger
property_tax_rate_percentnumber
expected_appreciationobjectrequiredThe expected yearly appreciation of the home's market and of the home, in percent a year. The market figure is the area's long-run rate (its five-year rate where no long-run window exists). The home figure adds the edge: the average amount by which homes with the same rank beat or trailed their own market in historical tests. The edge is 0 when that rank performed in line with its market.
ShowHide 9 fields in expected_appreciation
statusstringrequiredready: both figures. market_only: the home has no scored rank, so only the market figure is given. unavailable: we have no appreciation history for the area.
One of
readymarket_onlyunavailablemarket_percent_per_yearnumberhome_percent_per_yearnumbermarket_percent_per_year plus edge_percent_per_year.
edge_percent_per_yearnumberThe average for homes ranked like this one, against their own market. A single home varies around it.
home_low_percent_per_yearnumberThe market figure plus the 10th percentile result for single homes ranked like this one.
home_high_percent_per_yearnumberThe market figure plus the 90th percentile result for single homes ranked like this one.
market_windowstringWhich window of market history the market figure comes from.
One of
long_runrecentfrom_yearintegerto_yearinteger
Status codes
200400401402404422429500Error codes
curl https://api.goodinvestment.io/v1/properties/read \
-H "Authorization: Bearer $GI_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"line1": "101 Sample Ridge Dr",
"city": "Austin",
"state": "TX",
"zip": "78704"
},
"asking_price": 689000
}'{
"as_of": "2026-11-14",
"external_id": null,
"address": {
"line1": "101 Sample Ridge Dr",
"city": "Austin",
"state": "TX",
"zip": "78704"
},
"price_used": {"amount": 689000.0, "source": "asking_price"},
"appreciation_rank": {
"status": "scored",
"score": 8.4,
"local_percentile": 84,
"band": "Top tier",
"confidence": "High"
},
"selection_rank": {"status": "scored", "local_percentile": 79},
"cost_to_own": {
"status": "ready",
"rate_percent": 6.24,
"rate_source": "freddie_mac_pmms",
"rate_as_of": "2026-11-12",
"down_payment_percent": 20.0,
"term_months": 360,
"loan_amount": 551200.0,
"principal_and_interest": 3390.25,
"property_tax": 1041.71,
"property_tax_rate_percent": 1.8143,
"property_tax_basis": "zip",
"insurance": 241.15,
"hoa": 0.0,
"mortgage_insurance": 0.0,
"total": 4673.11,
"includes_hoa": true
},
"price_vs_value": {
"status": "ready",
"asking_price": 689000.0,
"estimated_value": 702000,
"estimated_value_low": 661000,
"estimated_value_high": 744000,
"estimate_source": "third_party_avm",
"estimate_as_of": "2026-11-10",
"difference_percent": -1.9,
"flag": "near_value"
},
"market": {
"zip": "78704",
"county": "Travis",
"state": "TX",
"index_basis": "zip",
"recent_appreciation": {
"percent_per_year": 1.9,
"from_year": 2020,
"to_year": 2025
},
"long_run_appreciation": {
"percent_per_year": 5.8,
"from_year": 2000,
"to_year": 2025
},
"property_tax_rate_percent": 1.8143
},
"expected_appreciation": {
"status": "ready",
"market_percent_per_year": 5.8,
"home_percent_per_year": 12.56,
"edge_percent_per_year": 6.76,
"home_low_percent_per_year": -0.01,
"home_high_percent_per_year": 31.5,
"market_window": "long_run",
"from_year": 2000,
"to_year": 2025
},
"read_id": "rd_example01",
"reads_billed": 0,
"livemode": false
}API reference
Rank a list
https://api.goodinvestment.io/v1/lists/rankSend up to 100 homes in one call, or up to 250 on an Enterprise contract, and get them back in order. Each row needs latitude, longitude, price, sqft, city and state, and can carry zip, property_type, beds, baths, year_built and your external_id. We place each home in its local market by its city and state and use your data as sent, with no lookup, so a row missing coordinates, city or state comes back as a row error and costs nothing. Each ranked row is 1 read.
Rows are grouped by the local market each home is ranked in and ordered inside each group. Ranked rows come first, group by group, followed by every row that was not ranked, in the order you sent them.
Billing and plans
Each ranked row bills 1 read, the same as reading that home on its own, and a row we could not rank bills nothing. A list that would take you past your plan's reads is refused whole with quota_exhausted before any row is scored, so a list is never half billed. Release mode and rows by address are on the Enterprise plan, and a live key on another plan gets plan_required for them. A test key takes both against the sample homes, and its rows bill nothing.
price_range orders homes inside a buyer's range
Give the range on price (price_min, price_max) or on price per square foot (price_per_sqft_min, price_per_sqft_max). Inside each market group the rows are ordered by Appreciation Rank, highest first, with the selection rank breaking ties, and position 1 is the best fit.
release chooses which owned homes to sell first (Enterprise)
Inside each market group the rows split into 5 bands of equal count by price per square foot, so what you sell and what you keep share a price mix. A group with fewer than 10 rows is one band. Inside each band the rows are ordered by release_rank, lowest first, and the lowest release_fraction of the band (default 0.2) is marked "release": true. A band needs at least 1 / release_fraction rows before any row in it is marked, and the group's note tells you when your bands are smaller than that, as it does in the example.
Rows by address (Enterprise)
A row may carry address (line1, city, state, zip) in place of the details a row otherwise needs. We look the home up and, when the row has no price, rank it at its value estimate. Each ranked address row is 1 read, and a call takes up to 25 of them. Every ranked row reports price_source, supplied or estimated_value. Both list modes were measured on recorded sale prices, and a list ranked on estimated values is a different input.
Row status
ranked- Meaning
- Ordered in its market group, with its position, ranks and price_source.
- Bills
- 1 read
out_of_range- Meaning
- Outside the price range you sent, so left unranked.
- Bills
- Nothing
not_scored- Meaning
- We have no rank for this home. Every rank field is null.
- Bills
- Nothing
error- Meaning
- The row is missing a field or holds a bad value. error names the code, the message and the field.
- Bills
- Nothing
Body params
modestringrequiredprice_range orders homes inside a buyer's range. release (Enterprise) orders owned homes for sale.
One of
price_rangereleaseprice_minnumberprice_range: the lowest price to rank.
price_maxnumberprice_range: the highest price to rank.
price_per_sqft_minnumberprice_range: the range on price per square foot, in place of price_min.
price_per_sqft_maxnumberprice_range: the range on price per square foot, in place of price_max.
release_fractionnumberDefaults to0.2release: the share of each band marked for release.
rowsarray of objectsrequiredAt most 100, unless an Enterprise contract sets another figure (never above 250). At most 25 rows by address.
ShowHide 15 fields in rows
addressobjectEnterprise: the home's address in place of its details. We look it up.
ShowHide 4 fields in address
line1stringrequiredStreet number and name
citystringrequiredstatestringrequiredTwo-letter state code.
zipstringrequired5-digit ZIP code; ZIP+4 is accepted and cut to 5 digits.
latitudenumberlongitudenumberpricenumberThe price to rank the home at.
sqftnumberzipstringcitystringPlaces the home in its local market
statestringTwo-letter state code.
property_typestringbedsnumberbathsnumberyear_builtintegerlot_sqftnumberhoa_monthlynumberexternal_idstring
Response
read_idstringreads_billednumberas_ofstringlivemodebooleanmodestringOne of
price_rangereleaserangeobjectShowHide 3 fields in range
basisstringOne of
priceprice_per_sqftminnumbermaxnumber
release_fractionnumberrows_receivedintegerrows_rankedintegergroupsarray of objectsShowHide 4 fields in groups
market_groupstringrows_rankedintegerbandsintegernotestring
rowsarray of objectsRanked rows first, market group by market group in order, then every unranked row in request order.
ShowHide 13 fields in rows
indexintegerThe row's position in your request
external_idstringstatusstringOne of
rankedout_of_rangenot_scorederrormarket_groupstringpositionintegerprice_range: 1 is the best in its market group. release: 1 is the first to release in its band.
bandintegerrelease only. 1 is the lowest price per square foot.
releasebooleanprice_sourcestringThe price this row was ranked at: the one you sent, or the value estimate for an address row sent without one. Both list modes were measured on recorded sale prices, and a list ranked on estimated values is a different input.
One of
suppliedestimated_valueappreciation_rankobjectWhere the home ranks for appreciation potential among homes in its own local market.
scoreis 0 to 10 andlocal_percentile0 to 100.confidenceis present wheneverscoreis, and a display of the score must show it: High when the home's own market has enough homes to rank against, Medium when it is ranked against a broader reference.ShowHide 5 fields in appreciation_rank
statusstringrequiredOne of
scorednot_scoredscorenumberrequiredlocal_percentileintegerrequiredbandstringrequired8 and up Top tier, 7 Strong, 5.5 Above average, 4 Around the median, below that Below the median.
One of
Top tierStrongAbove averageAround the medianBelow the medianconfidencestringrequiredOne of
HighMedium
selection_rankobjectA second, separate rank of the home within its local market, used to break ties when a list is ordered. It is never combined with the Appreciation Rank.
ShowHide 2 fields in selection_rank
statusstringrequiredOne of
scorednot_scoredlocal_percentileintegerrequired
release_rankobjectThe rank
releasemode orders by, lowest first, within the home's local market. Present on release rows only.ShowHide 2 fields in release_rank
statusstringrequiredOne of
scorednot_scoredlocal_percentileintegerrequired
errorobjectShowHide 3 fields in error
codestringmessagestringfieldstring
reads_billednumber1 for a ranked row, 0 otherwise.
One of
01
Status codes
200400401402403422429500Error codes
curl https://api.goodinvestment.io/v1/lists/rank \
-H "Authorization: Bearer $GI_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "price_range",
"price_min": 300000,
"price_max": 1000000,
"rows": [
{
"external_id": "sbx_01",
"latitude": 30.24512,
"longitude": -97.76831,
"price": 689000,
"sqft": 1610,
"city": "Austin",
"state": "TX"
},
{
"external_id": "sbx_04",
"latitude": 30.24955,
"longitude": -97.76248,
"price": 329000,
"sqft": 742,
"city": "Austin",
"state": "TX"
},
{
"external_id": "sbx_06",
"latitude": 30.25218,
"longitude": -97.77904,
"price": 1395000,
"sqft": 3120,
"city": "Austin",
"state": "TX"
},
{
"external_id": "sbx_05",
"latitude": 30.23411,
"longitude": -97.77593,
"price": 612000,
"sqft": 1495,
"state": "TX"
}
]
}'{
"as_of": "2026-11-14",
"mode": "price_range",
"range": {"basis": "price", "min": 300000.0, "max": 1000000.0},
"release_fraction": null,
"rows_received": 4,
"rows_ranked": 2,
"groups": [
{"market_group": "Austin, TX", "rows_ranked": 2, "bands": null, "note": null}
],
"rows": [
{
"index": 0,
"external_id": "sbx_01",
"status": "ranked",
"market_group": "Austin, TX",
"position": 1,
"band": null,
"release": null,
"price_source": "supplied",
"appreciation_rank": {
"status": "scored",
"score": 8.4,
"local_percentile": 84,
"band": "Top tier",
"confidence": "High"
},
"selection_rank": {"status": "scored", "local_percentile": 79},
"release_rank": {"status": "not_scored", "local_percentile": null},
"error": null,
"reads_billed": 0
},
{
"index": 1,
"external_id": "sbx_04",
"status": "ranked",
"market_group": "Austin, TX",
"position": 2,
"band": null,
"release": null,
"price_source": "supplied",
"appreciation_rank": {
"status": "scored",
"score": 7.3,
"local_percentile": 73,
"band": "Strong",
"confidence": "High"
},
"selection_rank": {"status": "scored", "local_percentile": 70},
"release_rank": {"status": "not_scored", "local_percentile": null},
"error": null,
"reads_billed": 0
},
{
"index": 2,
"external_id": "sbx_06",
"status": "out_of_range",
"market_group": null,
"position": null,
"band": null,
"release": null,
"price_source": null,
"appreciation_rank": {
"status": "not_scored",
"score": null,
"local_percentile": null,
"band": null,
"confidence": null
},
"selection_rank": {"status": "not_scored", "local_percentile": null},
"release_rank": {"status": "not_scored", "local_percentile": null},
"error": null,
"reads_billed": 0
},
{
"index": 3,
"external_id": "sbx_05",
"status": "error",
"market_group": null,
"position": null,
"band": null,
"release": null,
"price_source": null,
"appreciation_rank": {
"status": "not_scored",
"score": null,
"local_percentile": null,
"band": null,
"confidence": null
},
"selection_rank": {"status": "not_scored", "local_percentile": null},
"release_rank": {"status": "not_scored", "local_percentile": null},
"error": {
"code": "invalid_request",
"message": "rows[3].city is required.",
"field": "rows[3].city"
},
"reads_billed": 0
}
],
"read_id": "rd_example03",
"reads_billed": 0,
"livemode": false
}API reference
Read a ZIP
https://api.goodinvestment.io/v1/zips/{zip}/appreciationSend a ZIP code and get its appreciation over one year, five years and since 2000. Add neighborhoods=h3 for the same three figures for each neighborhood in it. A neighborhood comes back as the H3 cells (resolution 8, about 0.7 km² each) that share its figures, so you can join your own homes to it by the H3 cell of their coordinates. Where a neighborhood is too small to hold a hex, the hex it sits in comes back as its resolution-9 cells (about 0.1 km² each), so in dense blocks match on both resolutions.
Every neighborhood figure carries a basis and an estimated flag. basis names the area the figure comes from: the neighborhood itself, or the ZIP's own figures where nothing is published for the neighborhood. estimated is true when a year at either end of the window was left blank and we carried the neighborhood's last published level forward with its ZIP's change.
current_year_estimate covers the year whose annual figures are not out yet. It updates every month from late March to late January as new monthly data comes out, then in late February with the year's fourth quarter, and the annual figures in spring replace it. through_month is the last month of data it uses, method says whether it is our monthly estimate or the metro's change over the quarters published so far, and region names the area whose change it uses.
Each call is 1 read, whatever the ZIP's size. Add history=annual for each year's change since 2001.
Path and query params
zipstringrequiredA five-digit ZIP code.
historystringDefaults tononeannualadds each year's change since 2001 to the ZIP and to every neighborhood.One of
noneannualneighborhoodsstringDefaults tononeh3addsneighborhoods: every neighborhood in the ZIP as its H3 cells with its figures. Without it you get the ZIP's figures only. One read either way.One of
noneh3
Response
read_idstringreads_billednumberas_ofstringlivemodebooleanzipstringcountystringstatestringdata_throughintegerThe last year of the current annual figures. A neighborhood's windows end here, or at the last year its ZIP's or county's figures reach where nothing later is published.
zip_appreciationobjectThe figures a property read returns in
marketfor a home in this ZIP. They come from the ZIP's own index when it is current, else from the county's, else from the state's.ShowHide 5 fields in zip_appreciation
basisstringOne of
zipcountystateone_yearobjectShowHide 3 fields in one_year
percent_per_yearnumberfrom_yearintegerto_yearinteger
five_yearobjectShowHide 3 fields in five_year
percent_per_yearnumberfrom_yearintegerto_yearinteger
since_2000objectShowHide 3 fields in since_2000
percent_per_yearnumberfrom_yearintegerto_yearinteger
historyarray of objectsWith history=annual only.
ShowHide 4 fields in history
yearintegerpercentnumberThe change from the year before.
basisstringOne of
neighborhoodzipcountystateestimatedboolean
current_year_estimateobjectThe year after
data_through, estimated until its annual figures are published. It updates every month from late March to late January as new monthly data comes out, and in late February with the year's fourth quarter; the annual figures in spring replace it. It applies to the ZIP and to every neighborhood whose figures run todata_through.ShowHide 8 fields in current_year_estimate
statusstringnone for a ZIP whose figures stop before data_through.
One of
readynonefrom_yearintegerto_yearintegerpercentnumberEstimated change in the year's average level from the year before, in percent.
through_quarterstringThe last quarter of index data the estimate uses.
through_monthstringThe last month of index data the estimate uses. It moves forward each month.
methodstringmonthly: our monthly estimate, from quarterly and monthly house price indexes, state unemployment and the 10-year Treasury yield. quarterly: the metro's change over the quarters published so far.
One of
monthlyquarterlyregionstringThe area whose change the estimate uses: the metro, the state outside its metro areas, or the state.
neighborhoodsobjectWith neighborhoods=h3 only.
ShowHide 3 fields in neighborhoods
statusstringnone_in_zip: the ZIP has no land area of its own, such as a PO box ZIP, so only the ZIP figures are given.
One of
readynone_in_ziphex_resolutionintegerThe H3 resolution of the hexes (about 0.7 km² each). Where a neighborhood is too small to hold one, the hex it sits in comes back as its resolution-9 cells (about 0.1 km² each).
itemsarray of objectsShowHide 6 fields in items
cellsarray of stringsThe neighborhood's H3 cells inside this ZIP: resolution 8, or resolution 9 inside a hex it shares with a neighborhood too small to hold a hex of its own. Read a cell's resolution from the cell itself.
published_throughintegerThe last year with a figure of the neighborhood's own, from a published index or, where none covers it, from our own index; null when it has none.
one_yearobjectShowHide 5 fields in one_year
percent_per_yearnumberCompound appreciation per year over the window.
from_yearintegerWhere our own index covers the neighborhood, a window starts at the index's first year when that is later than the window's usual start.
to_yearintegerbasisstringThe area the figure comes from: the neighborhood itself, or, where neither a published index nor our own index has a figure for the neighborhood over the window, the ZIP's own figures with their basis.
One of
neighborhoodzipcountystateestimatedbooleantrue when the neighborhood had no published figure for a year at either end of the window, and we carried its last published level with the ZIP's change (else the county's) over the missing years.
five_yearobjectShowHide 5 fields in five_year
percent_per_yearnumberCompound appreciation per year over the window.
from_yearintegerWhere our own index covers the neighborhood, a window starts at the index's first year when that is later than the window's usual start.
to_yearintegerbasisstringThe area the figure comes from: the neighborhood itself, or, where neither a published index nor our own index has a figure for the neighborhood over the window, the ZIP's own figures with their basis.
One of
neighborhoodzipcountystateestimatedbooleantrue when the neighborhood had no published figure for a year at either end of the window, and we carried its last published level with the ZIP's change (else the county's) over the missing years.
since_2000objectShowHide 5 fields in since_2000
percent_per_yearnumberCompound appreciation per year over the window.
from_yearintegerWhere our own index covers the neighborhood, a window starts at the index's first year when that is later than the window's usual start.
to_yearintegerbasisstringThe area the figure comes from: the neighborhood itself, or, where neither a published index nor our own index has a figure for the neighborhood over the window, the ZIP's own figures with their basis.
One of
neighborhoodzipcountystateestimatedbooleantrue when the neighborhood had no published figure for a year at either end of the window, and we carried its last published level with the ZIP's change (else the county's) over the missing years.
historyarray of objectsWith history=annual only.
ShowHide 4 fields in history
yearintegerpercentnumberThe change from the year before.
basisstringOne of
neighborhoodzipcountystateestimatedboolean
Status codes
200400401402404429500Error codes
curl "https://api.goodinvestment.io/v1/zips/78704/appreciation?neighborhoods=h3" \
-H "Authorization: Bearer $GI_TEST_KEY"{
"as_of": "2026-11-14",
"zip": "78704",
"county": "Travis",
"state": "TX",
"data_through": 2025,
"zip_appreciation": {
"basis": "zip",
"one_year": {"percent_per_year": 1.9, "from_year": 2024, "to_year": 2025},
"five_year": {"percent_per_year": 1.9, "from_year": 2020, "to_year": 2025},
"since_2000": {"percent_per_year": 5.8, "from_year": 2000, "to_year": 2025}
},
"current_year_estimate": {
"status": "ready",
"from_year": 2025,
"to_year": 2026,
"percent": 1.2,
"through_quarter": "2026-Q2",
"through_month": "2026-08",
"method": "monthly",
"region": "Sample Metro, TX"
},
"neighborhoods": {
"status": "ready",
"hex_resolution": 8,
"items": [
{
"cells": [
"88489e3441fffff",
"88489e3445fffff",
"88489e3449fffff",
"88489e344bfffff",
"88489e344dfffff",
"88489e3623fffff",
"88489e3627fffff",
"88489e3635fffff",
"88489e3713fffff",
"88489e371bfffff"
],
"published_through": 2025,
"one_year": {
"percent_per_year": 2.7,
"from_year": 2024,
"to_year": 2025,
"basis": "neighborhood",
"estimated": false
},
"five_year": {
"percent_per_year": 2.7,
"from_year": 2020,
"to_year": 2025,
"basis": "neighborhood",
"estimated": false
},
"since_2000": {
"percent_per_year": 6.6,
"from_year": 2000,
"to_year": 2025,
"basis": "neighborhood",
"estimated": false
}
},
{
"cells": ["88489e3443fffff", "88489e345dfffff", "88489e3637fffff"],
"published_through": null,
"one_year": {
"percent_per_year": 1.9,
"from_year": 2024,
"to_year": 2025,
"basis": "zip",
"estimated": false
},
"five_year": {
"percent_per_year": 1.9,
"from_year": 2020,
"to_year": 2025,
"basis": "zip",
"estimated": false
},
"since_2000": {
"percent_per_year": 5.8,
"from_year": 2000,
"to_year": 2025,
"basis": "zip",
"estimated": false
}
},
{
"cells": [
"88489e3621fffff",
"88489e3625fffff",
"88489e3629fffff",
"88489e362bfffff",
"88489e362dfffff",
"88489e363dfffff"
],
"published_through": 2023,
"one_year": {
"percent_per_year": 1.9,
"from_year": 2024,
"to_year": 2025,
"basis": "neighborhood",
"estimated": true
},
"five_year": {
"percent_per_year": 1.5,
"from_year": 2020,
"to_year": 2025,
"basis": "neighborhood",
"estimated": true
},
"since_2000": {
"percent_per_year": 5.2,
"from_year": 2000,
"to_year": 2025,
"basis": "neighborhood",
"estimated": true
}
}
]
},
"read_id": "rd_example07",
"reads_billed": 0,
"livemode": false
}API reference
Get usage
https://api.goodinvestment.io/v1/usageYour plan, reads used and remaining this billing month, the rows your lists have ranked, and the date the reads reset. The key page shows the same numbers. The call is free, and calls made with a test key are never counted.
Response
planstringOne of
trialbuildergrowthscaleenterpriselist_rows_usedintegerRows ranked by lists.rank this month.
list_rows_includedintegerA monthly cap on ranked list rows, set only by contract. null, the default on every plan, means no cap: list rows bill reads like any other ranked home.
monthstringreads_usednumberreads_includedintegerreads_remainingnumberoverage_enabledbooleanresets_onstringlivemodeboolean
Status codes
200401429Error codes
curl https://api.goodinvestment.io/v1/usage \
-H "Authorization: Bearer $GI_TEST_KEY"{
"list_rows_used": 0,
"list_rows_included": null,
"plan": "trial",
"month": "2026-11",
"reads_used": 0.0,
"reads_included": 25,
"reads_remaining": 25.0,
"overage_enabled": false,
"resets_on": "2026-12-01",
"livemode": false
}Resources
Errors
Errors return one shape, with message in plain language and field naming the input at fault when there is one. A call that fails bills nothing.
400
- Code
invalid_request- What to do
- Fix the field named in the error.
401
- Code
unauthorized- What to do
- Check the key, or create a new one if it was revoked. A live key needs a paid plan.
402
- Code
quota_exhausted- What to do
- The call would pass your plan's reads for the month. Move up a plan, or wait for the reset: the same day of the month you bought the plan (the 1st on the trial).
403
- Code
plan_required- What to do
- Release mode and rows by address are on the Enterprise plan. Use a test key to build against them.
404
- Code
not_found- What to do
- We found no property record at that address, or have no figures for that ZIP code. Check it, or send the homeās details in attributes.
422
- Code
invalid_request- What to do
- The Idempotency-Key was used with a different body. Use a new key.
429
- Code
rate_limited- What to do
- Your account can send 60 requests a minute (120 on Scale), and address lookups can pause until 00:00 UTC. Wait the seconds in Retry-After and send again.
500
- Code
internal_error- What to do
- Retry, and quote the request_id if it persists.
curl https://api.goodinvestment.io/v1/properties/read \
-H "Authorization: Bearer $GI_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"line1": "9 Nowhere Rd",
"city": "Austin",
"state": "TX",
"zip": "78704"
}
}'{
"error": {
"code": "not_found",
"message": "Test keys read only the sample homes listed in the API docs.",
"field": "address",
"request_id": "req_example01"
}
}Resources
Limits and headers
| Requests per account per minute | 60, or 120 on Scale |
|---|---|
| Rows per list call | 100, or up to 250 on Enterprise |
| Rows by address per call (Enterprise) | 25 |
| Idempotency-Key window | 24 hours |
Response headers
X-Request-Id- When
- Every response
- Holds
- A unique id for the request. Quote it when you contact us.
X-Reads-Billed- When
- Property, ZIP and list calls
- Holds
- Reads the call billed: 0 for a test key and for an idempotent repeat.
Retry-After- When
- A 429
- Holds
- Seconds to wait before you send again.
X-RateLimit-Limit- When
- Every response to an accepted key
- Holds
- Requests your account may send this minute, across all its keys.
X-RateLimit-Remaining- When
- Every response to an accepted key
- Holds
- Requests left this minute, counting this one.
X-RateLimit-Reset- When
- Every response to an accepted key
- Holds
- Seconds until the count starts again.
Resources
Serving many users
We count your account's requests across all its keys, in clock minutes that reset on the minute. If your product shows our reads to its own users, they tend to arrive together, so build for the busy minute:
- Cache reads on your side. Serve a home's repeat views from your cache, because every call bills a read and counts toward the minute.
- Read the rate headers. When
X-RateLimit-Remainingnears 0, hold new calls for theX-RateLimit-Resetseconds and send them once the count starts again. - Treat a 429 as a wait. A refused call bills nothing, so send it again after the
Retry-Afterseconds.
Scale allows 120 requests a minute and the other plans 60. If your busiest minute needs more, email support@goodinvestment.io and we raise the limit on your account.
Resources
Plans and pricing
Each plan allows 60 requests a minute per account (120 on Scale). Each home we rank is 1 read, whether you read it on its own or rank it in a list, and each ZIP is 1 read.
Builder
$149 /month
500 reads included
60 requests a minute
Growth
$499 /month
2,500 reads included
60 requests a minute
Scale
$1,499 /month
10,000 reads included
120 requests a minute
Enterprise
Rank lists at volume, with release mode to choose which homes to sell, rows by address and up to 250 rows a call, under limits set for your account. Priced by contract with a negotiated minimum and lower per-read rates.
support@goodinvestment.ioInstitutional pilot
Test the ranking on your own records before you license it. We score your past purchases or held book blind and point in time, against a pass bar sealed before scoring, and set the ranking to your price ranges or your book. Your data is deleted when the pilot ends.
support@goodinvestment.ioHow to sign up
- 1Open the API keys page and sign in, or create a free account there.
- 2Create a test key and build against the sample homes, free of charge.
- 3When you are ready for real homes, tick the API Terms box under Plans on the same page and choose a plan. Plans bill monthly and you can cancel at any time.
- 4Create a live key on the same page, and every call made with it bills against your plan.
For Enterprise or a pilot, email support@goodinvestment.io and we scope it with you.
Resources
Terms
Your use of the API is governed by the API Terms, including how you show a rank and its confidence. Questions go to support@goodinvestment.io.
Appreciation Rank, expected appreciation and estimated value are model-generated estimates, not investment advice or an appraisal.