Suggest US locations with explicit no-match handling
View all Realty in US Property & Mortgage Data endpoints →Search for US location suggestions with the required input string and optional numeric limit query parameter. Documented input forms include states, cities, districts, street addresses and ZIP codes; examples include California, Los Angeles and 2425 Sahalee Dr W Sammamish, WA. The documented parameter examples are input=new york and limit=10. The limit controls the requested number of response items; no offset, page token or guaranteed page traversal is documented for this operation. Recorded successful checks establish an autocomplete array and a meta.es_total_hits count. With input=New York and limit=3, the response had meta.es_total_hits=5731 and three candidates identified as state:ny, city:ny_new-york and city:ny_manhattan, with state_code=NY and country=USA. The total hit count therefore need not equal the number of returned suggestions. A deliberately nonexistent location returned HTTP 200, meta.es_total_hits=0 and autocomplete=[] without an error object. Treat that combination as a valid no-suggestions result rather than a failed request. These observations establish representative outcomes, not fixed counts, ranking or future candidate availability. A separate, truncated documentation example lists candidate fields _id, _score, area_type, centroid.lat, centroid.lon, city, state_code, country, counties with fips/name/state_code, geo_id and slug_id. It also includes type-dependent city_slug_id, county_needed_for_uniq, line, postal_code, has_catchment, school and school_id fields. These additional example fields were not all verified by the recorded checks and are not mandatory on every candidate. Preserve the selected candidate identity, type and available geography, then verify what the next endpoint accepts. Although the description mentions finding a property identifier from an address, the recorded checks do not establish guaranteed address-to-property resolution.
API Features
Live API Demo
🔒 Sign in to try it live
Log in to call this API with your own API key. New accounts get 100 free credits — no card required.
Log in / Sign upNo active API key found. Create one in your Dashboard, then reload this page. Dashboard →
/api/project/realty-in-us/locations-v2-auto-complete API Response (JSON)
{} curl -X GET 'https://api.opendata-api.com/api/project/realty-in-us/locations-v2-auto-complete?key=<API_KEY>&input=<input>'
Query Result
Use Cases
- Build a New York location picker that lets users distinguish the state, New York city and Manhattan candidates before selecting a search area.
- Show a no-suggestions message when autocomplete is empty and meta.es_total_hits is zero instead of repeatedly retrying a successful search.
- Display a short suggestion menu using limit while keeping the matching hit count separate from the number of visible candidates.
- Preserve the chosen suggestion's type and geography in application state, then validate the next property-search endpoint's accepted inputs.
- Test a shared search box with documented state, city, address and ZIP inputs without promising that every address resolves to a property.
Frequently asked questions
What kinds of text can I submit as input?
The documentation accepts states, cities, districts, street addresses and ZIP codes. New York suggestions were checked successfully; the supplied checks do not establish the behavior of every address or ZIP code.
Does an empty autocomplete array indicate an error?
Not by itself. A nonexistent-location check returned HTTP 200 with autocomplete=[] and meta.es_total_hits=0, without an error object. Give that combination a no-suggestions state in the interface.
Why can meta.es_total_hits be larger than the suggestion list?
The recorded New York request used limit=3, returned three suggestions and reported 5731 total hits. Keep the reported match count distinct from the returned list length; no offset or page-token parameter is documented here.
How should I distinguish state and city suggestions?
Preserve each returned candidate identity, location type and available geography. The checked New York response included state:ny, city:ny_new-york and city:ny_manhattan; choosing the first result would not necessarily represent the user's intended area.
Can every address suggestion be used as a property identifier?
No. Address-to-property lookup is a documented purpose, but the recorded checks only establish location suggestions and a zero-hit case. Confirm that a selected candidate actually carries an appropriate identifier and that the next endpoint accepts it.