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/read
POST/v1/lists/rank
GET/v1/zips/{zip}/appreciation
GET/v1/usage

Getting started

Quickstart

  1. 1
    Create a test key on the API keys page.
  2. 2
    Put it in your shell as export GI_TEST_KEY=gi_test_...
  3. 3
    Send 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
  }'
Response200
{
  "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.

The two kinds of API key. Column headers are buttons: click to sort, click again to reverse, and a third time to restore the original order.
gi_test_The sample homesNever
gi_live_Real US homesAgainst 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.

The sample homes a test key reads. Column headers are buttons: click to sort, click again to reverse, and a third time to restore the original order.
sbx_01101 Sample Ridge Dr, Austin, TX 7870430.24512, -97.768311,610$689,000
sbx_02214 Example Hollow Ln, Austin, TX 7870430.24187, -97.774122,245$915,000
sbx_0338 Demo Creek Ct, Austin, TX 7870430.23842, -97.781061,380$575,000
sbx_041407 Placeholder Ave, Austin, TX 7870430.24955, -97.76248742$329,000
sbx_05902 Specimen St, Austin, TX 7870430.23411, -97.775931,495$612,000
sbx_0655 Trial Oak Blvd, Austin, TX 7870430.25218, -97.779043,120$1,395,000
sbx_0777 Sample Terrace Rd, Columbus, OH 4320639.94127, -82.983151,340$289,000
sbx_08610 Example Park Dr, Columbus, OH 4320639.93802, -82.977211,885$365,000
sbx_0923 Demo Mill Way, Columbus, OH 4320639.94466, -82.989041,104$239,000
sbx_101180 Test Harbor Ln, Columbus, OH 4320639.93514, -82.992371,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

POSThttps://api.goodinvestment.io/v1/properties/read

Send 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 optionally asking_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
  • address and attributes with at least latitude, longitude and sqft, plus asking_price or estimated_value

    We do
    Read the home as you describe it, with no lookup. price_vs_value fills in when you send estimated_value; otherwise its status is no_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

  • Authorizationstringrequired

    Bearer gi_test_... or Bearer gi_live_...

  • Idempotency-Keystring

    Up to 200 characters. A repeat with the same body inside 24 hours bills nothing.

Body params

  • addressobjectrequired
    Show 4 fields in address
    • line1stringrequired

      Street number and name

    • citystringrequired
    • statestringrequired

      Two-letter state code.

    • zipstringrequired

      5-digit ZIP code; ZIP+4 is accepted and cut to 5 digits.

  • asking_pricenumber

    The list price or your offer. Without it the home is ranked at its estimated value.

  • attributesobject

    The home's details. Send them and we read the home as given, with no lookup.

    Show 9 fields in attributes
    • latitudenumberrequired
    • longitudenumberrequired
    • sqftnumberrequired

      Living area in square feet.

    • property_typestring
    • bedsnumber
    • bathsnumber
    • year_builtinteger
    • lot_sqftnumber
    • hoa_monthlynumber

      Monthly HOA dues. Sent as 0 when there is none; left out when unknown.

  • estimated_valuenumber or object

    Your own value estimate, as a number or an object with value, low, high and as_of.

    Show 4 fields in estimated_value
    • valuenumberrequired
    • lownumber
    • highnumber
    • as_ofstring

      The date your estimate was made.

  • financingobject

    The loan terms that price cost_to_own.

    Show 4 fields in financing
    • down_payment_percentnumberDefaults to 20
    • term_monthsintegerDefaults to 360

      180 prices at the 15-year rate; any other term at the 30-year rate.

    • rate_percentnumber

      Your mortgage rate. Without it we use Freddie Mac's latest weekly average.

    • insurance_annualnumber

      Without it

  • external_idstring

    Your own id

Response

  • read_idstringrequired

    Starts rd_.

  • reads_billednumberrequired

    One of01

  • as_ofstringrequired
  • livemodebooleanrequired

    False for a test key.

  • external_idstring
  • addressobject
    Show 4 fields in address
    • line1stringrequired

      Street number and name

    • citystringrequired
    • statestringrequired

      Two-letter state code.

    • zipstringrequired

      5-digit ZIP code; ZIP+4 is accepted and cut to 5 digits.

  • price_usedobject
    Show 2 fields in price_used
    • amountnumber
    • sourcestring

      One ofasking_priceestimated_value

  • appreciation_rankobjectrequired

    Where the home ranks for appreciation potential among homes in its own local market. score is 0 to 10 and local_percentile 0 to 100. confidence is present whenever score is, 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.

    Show 5 fields in appreciation_rank
    • statusstringrequired

      One ofscorednot_scored

    • scorenumberrequired
    • local_percentileintegerrequired
    • bandstringrequired

      8 and up Top tier, 7 Strong, 5.5 Above average, 4 Around the median, below that Below the median.

      One ofTop tierStrongAbove averageAround the medianBelow the median

    • confidencestringrequired

      One ofHighMedium

  • selection_rankobjectrequired

    A 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.

    Show 2 fields in selection_rank
    • statusstringrequired

      One ofscorednot_scored

    • local_percentileintegerrequired
  • cost_to_ownobjectrequired

    Monthly 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_unavailable and every amount is null; no stand-in rate prices the answer.

    Show 16 fields in cost_to_own
    • statusstringrequired

      One ofreadyrate_unavailableno_price

    • rate_percentnumber
    • rate_sourcestring

      One offreddie_mac_pmmssupplied

    • rate_as_ofstring
    • down_payment_percentnumber
    • term_monthsinteger
    • loan_amountnumber
    • principal_and_interestnumber
    • property_taxnumber
    • property_tax_rate_percentnumber
    • property_tax_basisstring

      zip: the county effective rate for the home's ZIP. national_default: 0.88% a year where we have no rate for the ZIP.

      One ofzipnational_default

    • insurancenumber
    • hoanumber
    • mortgage_insurancenumber
    • totalnumber
    • includes_hoaboolean

      False when HOA dues are unknown

  • price_vs_valueobjectrequired
    Show 9 fields in price_vs_value
    • statusstringrequired

      One ofreadyno_estimate_suppliedestimate_unavailableno_asking_price

    • asking_pricenumber
    • estimated_valuenumber
    • estimated_value_lownumber
    • estimated_value_highnumber
    • estimate_sourcestring

      third_party_avm: an automated valuation from our data provider, fetched on estimate_as_of. supplied: the value you sent.

      One ofthird_party_avmsupplied

    • estimate_as_ofstring
    • difference_percentnumber

      Asking price against the estimate

    • flagstring

      Against the estimate's low-to-high range; null when the estimate has no range.

      One ofbelow_valuenear_valueabove_value

  • marketobjectrequired

    House price index history for the home's area, and its property tax rate.

    Show 7 fields in market
    • zipstring
    • countystring
    • statestring
    • index_basisstring

      The narrowest area with a published house price index here.

      One ofzipcountystate

    • recent_appreciationobject
      Show 3 fields in recent_appreciation
      • percent_per_yearnumber
      • from_yearinteger
      • to_yearinteger
    • long_run_appreciationobject
      Show 3 fields in long_run_appreciation
      • percent_per_yearnumber
      • from_yearinteger
      • to_yearinteger
    • property_tax_rate_percentnumber
  • expected_appreciationobjectrequired

    The 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.

    Show 9 fields in expected_appreciation
    • statusstringrequired

      ready: 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 ofreadymarket_onlyunavailable

    • market_percent_per_yearnumber
    • home_percent_per_yearnumber

      market_percent_per_year plus edge_percent_per_year.

    • edge_percent_per_yearnumber

      The average for homes ranked like this one, against their own market. A single home varies around it.

    • home_low_percent_per_yearnumber

      The market figure plus the 10th percentile result for single homes ranked like this one.

    • home_high_percent_per_yearnumber

      The market figure plus the 90th percentile result for single homes ranked like this one.

    • market_windowstring

      Which window of market history the market figure comes from.

      One oflong_runrecent

    • from_yearinteger
    • to_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
  }'
Response200
{
  "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

POSThttps://api.goodinvestment.io/v1/lists/rank

Send 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

  • modestringrequired

    price_range orders homes inside a buyer's range. release (Enterprise) orders owned homes for sale.

    One ofprice_rangerelease

  • price_minnumber

    price_range: the lowest price to rank.

  • price_maxnumber

    price_range: the highest price to rank.

  • price_per_sqft_minnumber

    price_range: the range on price per square foot, in place of price_min.

  • price_per_sqft_maxnumber

    price_range: the range on price per square foot, in place of price_max.

  • release_fractionnumberDefaults to 0.2

    release: the share of each band marked for release.

  • rowsarray of objectsrequired

    At most 100, unless an Enterprise contract sets another figure (never above 250). At most 25 rows by address.

    Show 15 fields in rows
    • addressobject

      Enterprise: the home's address in place of its details. We look it up.

      Show 4 fields in address
      • line1stringrequired

        Street number and name

      • citystringrequired
      • statestringrequired

        Two-letter state code.

      • zipstringrequired

        5-digit ZIP code; ZIP+4 is accepted and cut to 5 digits.

    • latitudenumber
    • longitudenumber
    • pricenumber

      The price to rank the home at.

    • sqftnumber
    • zipstring
    • citystring

      Places the home in its local market

    • statestring

      Two-letter state code.

    • property_typestring
    • bedsnumber
    • bathsnumber
    • year_builtinteger
    • lot_sqftnumber
    • hoa_monthlynumber
    • external_idstring

Response

  • read_idstring
  • reads_billednumber
  • as_ofstring
  • livemodeboolean
  • modestring

    One ofprice_rangerelease

  • rangeobject
    Show 3 fields in range
    • basisstring

      One ofpriceprice_per_sqft

    • minnumber
    • maxnumber
  • release_fractionnumber
  • rows_receivedinteger
  • rows_rankedinteger
  • groupsarray of objects
    Show 4 fields in groups
    • market_groupstring
    • rows_rankedinteger
    • bandsinteger
    • notestring
  • rowsarray of objects

    Ranked rows first, market group by market group in order, then every unranked row in request order.

    Show 13 fields in rows
    • indexinteger

      The row's position in your request

    • external_idstring
    • statusstring

      One ofrankedout_of_rangenot_scorederror

    • market_groupstring
    • positioninteger

      price_range: 1 is the best in its market group. release: 1 is the first to release in its band.

    • bandinteger

      release only. 1 is the lowest price per square foot.

    • releaseboolean
    • price_sourcestring

      The 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 ofsuppliedestimated_value

    • appreciation_rankobject

      Where the home ranks for appreciation potential among homes in its own local market. score is 0 to 10 and local_percentile 0 to 100. confidence is present whenever score is, 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.

      Show 5 fields in appreciation_rank
      • statusstringrequired

        One ofscorednot_scored

      • scorenumberrequired
      • local_percentileintegerrequired
      • bandstringrequired

        8 and up Top tier, 7 Strong, 5.5 Above average, 4 Around the median, below that Below the median.

        One ofTop tierStrongAbove averageAround the medianBelow the median

      • confidencestringrequired

        One ofHighMedium

    • selection_rankobject

      A 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.

      Show 2 fields in selection_rank
      • statusstringrequired

        One ofscorednot_scored

      • local_percentileintegerrequired
    • release_rankobject

      The rank release mode orders by, lowest first, within the home's local market. Present on release rows only.

      Show 2 fields in release_rank
      • statusstringrequired

        One ofscorednot_scored

      • local_percentileintegerrequired
    • errorobject
      Show 3 fields in error
      • codestring
      • messagestring
      • fieldstring
    • reads_billednumber

      1 for a ranked row, 0 otherwise.

      One of01

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"
      }
    ]
  }'
Response200
{
  "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

GEThttps://api.goodinvestment.io/v1/zips/{zip}/appreciation

Send 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

  • zipstringrequired

    A five-digit ZIP code.

  • historystringDefaults to none

    annual adds each year's change since 2001 to the ZIP and to every neighborhood.

    One ofnoneannual

  • neighborhoodsstringDefaults to none

    h3 adds neighborhoods: 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 ofnoneh3

Response

  • read_idstring
  • reads_billednumber
  • as_ofstring
  • livemodeboolean
  • zipstring
  • countystring
  • statestring
  • data_throughinteger

    The 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_appreciationobject

    The figures a property read returns in market for 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.

    Show 5 fields in zip_appreciation
    • basisstring

      One ofzipcountystate

    • one_yearobject
      Show 3 fields in one_year
      • percent_per_yearnumber
      • from_yearinteger
      • to_yearinteger
    • five_yearobject
      Show 3 fields in five_year
      • percent_per_yearnumber
      • from_yearinteger
      • to_yearinteger
    • since_2000object
      Show 3 fields in since_2000
      • percent_per_yearnumber
      • from_yearinteger
      • to_yearinteger
    • historyarray of objects

      With history=annual only.

      Show 4 fields in history
      • yearinteger
      • percentnumber

        The change from the year before.

      • basisstring

        One ofneighborhoodzipcountystate

      • estimatedboolean
  • current_year_estimateobject

    The 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 to data_through.

    Show 8 fields in current_year_estimate
    • statusstring

      none for a ZIP whose figures stop before data_through.

      One ofreadynone

    • from_yearinteger
    • to_yearinteger
    • percentnumber

      Estimated change in the year's average level from the year before, in percent.

    • through_quarterstring

      The last quarter of index data the estimate uses.

    • through_monthstring

      The last month of index data the estimate uses. It moves forward each month.

    • methodstring

      monthly: 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 ofmonthlyquarterly

    • regionstring

      The area whose change the estimate uses: the metro, the state outside its metro areas, or the state.

  • neighborhoodsobject

    With neighborhoods=h3 only.

    Show 3 fields in neighborhoods
    • statusstring

      none_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 ofreadynone_in_zip

    • hex_resolutioninteger

      The 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 objects
      Show 6 fields in items
      • cellsarray of strings

        The 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_throughinteger

        The 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_yearobject
        Show 5 fields in one_year
        • percent_per_yearnumber

          Compound appreciation per year over the window.

        • from_yearinteger

          Where 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_yearinteger
        • basisstring

          The 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 ofneighborhoodzipcountystate

        • estimatedboolean

          true 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_yearobject
        Show 5 fields in five_year
        • percent_per_yearnumber

          Compound appreciation per year over the window.

        • from_yearinteger

          Where 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_yearinteger
        • basisstring

          The 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 ofneighborhoodzipcountystate

        • estimatedboolean

          true 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_2000object
        Show 5 fields in since_2000
        • percent_per_yearnumber

          Compound appreciation per year over the window.

        • from_yearinteger

          Where 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_yearinteger
        • basisstring

          The 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 ofneighborhoodzipcountystate

        • estimatedboolean

          true 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 objects

        With history=annual only.

        Show 4 fields in history
        • yearinteger
        • percentnumber

          The change from the year before.

        • basisstring

          One ofneighborhoodzipcountystate

        • estimatedboolean

Status codes

200400401402404429500Error codes

curl "https://api.goodinvestment.io/v1/zips/78704/appreciation?neighborhoods=h3" \
  -H "Authorization: Bearer $GI_TEST_KEY"
Response200
{
  "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

GEThttps://api.goodinvestment.io/v1/usage

Your 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

  • planstring

    One oftrialbuildergrowthscaleenterprise

  • list_rows_usedinteger

    Rows ranked by lists.rank this month.

  • list_rows_includedinteger

    A 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.

  • monthstring
  • reads_usednumber
  • reads_includedinteger
  • reads_remainingnumber
  • overage_enabledboolean
  • resets_onstring
  • livemodeboolean

Status codes

200401429Error codes

curl https://api.goodinvestment.io/v1/usage \
  -H "Authorization: Bearer $GI_TEST_KEY"
Response200
{
  "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"
    }
  }'
Response404
{
  "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

Request and list limits on the monthly plans. Column headers are buttons: click to sort, click again to reverse, and a third time to restore the original order.
Requests per account per minute60, or 120 on Scale
Rows per list call100, or up to 250 on Enterprise
Rows by address per call (Enterprise)25
Idempotency-Key window24 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-Remaining nears 0, hold new calls for the X-RateLimit-Reset seconds 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-After seconds.

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.io

Institutional 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.io

How to sign up

  1. 1
    Open the API keys page and sign in, or create a free account there.
  2. 2
    Create a test key and build against the sample homes, free of charge.
  3. 3
    When 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.
  4. 4
    Create 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.