
This page is for an engineer at a single-family rental fund. The acquisitions team screens properties on an internal tool and wants a neighborhood data API to score the surroundings of each one before anyone visits. Our neighborhood guide for investors covers what to look for in person.
Public neighborhood data and its limits
The Census Bureau's API serves the 2020 to 2024 American Community Survey 5-year estimates. They reach down to census tracts and block groups. Variable B25077_001E, for example, is the median value of owner-occupied units in an area.
For schools, the Education Department's Common Core of Data is an annual database of every public elementary and secondary school and district. It carries no ratings. Neither source lists what sits 0.2 miles from one property.
What a neighborhood data API returns
Our location red-flags call takes one field, address, and answers as a stream of Server-Sent Events. The docs give examples of flags from bars and liquor stores to power lines and visible blight.
| Field in the API docs | What it holds |
|---|---|
| flag_type | What the nearby place is, for example Transit Station |
| category | The group the type falls in, for example Transportation |
| distance_miles | Distance from the property |
| importance | A weight from 1 to 5 |
| flag_score | The score for that flag. The docs give no range |
| name | The place's own name. Our example leaves it out |
| total_flags, aggregate_risk_score | The flag count, and a score from 0 to 10 |
| risk_level | None, Low, Moderate or High |
| school_ratings (info call) | Per school, name, rating, parent_rating, distance_in_miles, grades, student_count, funding_type and education_levels |
A fresh run costs 5 credits. The docs say a repeat of the same address by the same account within the cache TTL costs 0 credits and replays every event. A 400, 401 or 402 error costs 0 credits.
School ratings come from a second call. Our info endpoint returns a school_ratings list for 2 credits, and its docs say the ratings are refreshed annually.
A real example from a Homesage.ai API call
We ran both calls on one single-family property in Baltimore, Maryland, on 2026-11-07. A 1-credit search found the property, so the 3 calls used 8 credits.
| What the calls returned | One Baltimore property |
|---|---|
| Events, in order | run_started, geocoded, area_classified, flags_detected, vision_analyzed, complete |
| area_type | Urban |
| detection_mode | single |
| search_radius_miles | 0.3 |
| total_flags | 7 |
| Flags by category | Transportation 4, Adult/Vice 2, Commercial/Industrial 1 |
| Nearest flag | Manufacturing Plant / Factory, 0.12 miles, importance 4, flag_score 0.68 |
| vision_analyzed count | 0 |
| aggregate_risk_score | 0.55 |
| risk_level | Low |
| school_ratings | 4 schools. 3 public, rated 4, 2 and 2. 1 private, rating null |
| Credits | 1 for the search, 5 for the stream, 2 for info |
| info response time | 474 milliseconds |
Seven flags sat within 0.3 miles, and the aggregate score came out at 0.55 out of 10, labeled Low. Four of the 7 were transit stations with importance 2. The nearest flag, a manufacturing plant, had the highest flag_score at 0.68.

Seven red flags within 0.3 miles of one Baltimore property came with an aggregate risk score of 0.55 out of 10.
The stream sent run_started before the 5 events the docs list, and the vision step flagged nothing. In the info call, 3 public schools came back rated 4, 2 and 2. The private school had a null rating and a parent_rating of 5.

How to wire the 2 calls

- Open the stream. POST the address to the red-flags stream. A fresh run costs 5 credits.
- Show the progress events. geocoded, area_classified, flags_detected and vision_analyzed arrive before the result. Our run also sent run_started first.
- Read the complete event. It holds total_flags, aggregate_risk_score, risk_level and the flags list. The docs say to use its payload as the final response.
- Add school ratings. GET info returns school_ratings for 2 credits.
- Handle errors and nulls. An error event ends the run, and the docs say errored runs never reach the cache. A school rating can be null.
Here is the stream call. The -N flag stops curl from buffering the events.
curl -N -X POST "https://api.homesage.ai/api/properties/red-flags/stream/" \ -H "Authorization: Bearer $HOMESAGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"address": "<a US property address>"}' The complete event from our Baltimore run looked like this, trimmed to 2 of the 7 flags with the place names removed.
{ "area_type": "Urban", "detection_mode": "single", "search_radius_miles": 0.3, "total_flags": 7, "aggregate_risk_score": 0.55, "risk_level": "Low", "flags": [ {"name": "<removed>", "flag_type": "Manufacturing Plant / Factory", "category": "Commercial/Industrial", "distance_miles": 0.12, "importance": 4, "flag_score": 0.68}, {"name": "<removed>", "flag_type": "Transit Station", "category": "Transportation", "distance_miles": 0.21, "importance": 2, "flag_score": 0.33} ] } The full payload also echoes the address and coordinates. A cache hit adds from_cache and cached_at.
These fields describe places near a property, not the people who live there. They must not be used to steer buyers toward or away from an area. Federal fair-housing rules at 24 CFR 100.70(c) treat steering as unlawful.
Common neighborhood data mistakes
- Expecting exactly 5 events: Our run sent run_started first. Match each event by its name.
- Reading the flag count as the risk: Baltimore had 7 flags and a risk_level of Low. Read risk_level and aggregate_risk_score.
- Assuming a range for flag_score: The docs give ranges for importance and the aggregate score only.
- Treating a null rating as zero: The private school's rating came back null. Store it as missing.
- Paying for a re-run: A repeat run inside the cache TTL costs 0 credits. The cache key is per account and address.
Your account terms set where these outputs can be shown, so check them before a flag or a school rating reaches your own customers.
Estimated values. Not investment advice. Data as of 2026-11-07.
Frequently asked questions
What public data describes a neighborhood?
How do I get neighborhood data for an address?
What counts as a location red flag?
How is the neighborhood risk score scaled?
Does the API return school ratings?
Try the call
Run the red-flags stream on one property and read the complete event before you wire up a list. The API docs list every field and error code.
- Homesage.ai location red-flags stream and info call for one Baltimore, Maryland property, pulled 2026-11-07.
- Homesage.ai API docs, location red flags, read 2026-11-07.
- Homesage.ai API docs, property info, read 2026-11-07.
- US Census Bureau, American Community Survey 5-year data sets, 2020 to 2024 release.
- US Census Bureau, variable B25077_001E, median value.
- National Center for Education Statistics, Common Core of Data.
- 24 CFR 100.70, other prohibited sale and rental conduct, Legal Information Institute text.