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

Observed state and city candidate distinctions The New York check returned separate state:ny, city:ny_new-york and city:ny_manhattan candidates, supporting an explicit selection instead of automatically choosing the first suggestion.
Requested suggestions versus total matches Use the optional limit for the requested list size and meta.es_total_hits for matching-result context; a checked three-item response reported 5731 total hits.
Verified zero-hit success state Represent HTTP 200 with meta.es_total_hits=0 and autocomplete=[] as a legitimate no-match state, as observed for a nonexistent location.
Documented address and ZIP input breadth Accept state, city, district, address or ZIP-code search text in the same required input field while recognizing that address and ZIP outcomes were not established by the supplied checks.
Selection context without identifier assumptions Retain a candidate's identity, type and available geography for downstream validation without assuming every optional example field exists or every selection is a property.

Live API Demo

GET /api/project/realty-in-us/locations-v2-auto-complete

Request cost is temporarily unavailable. No price is assumed.

View pricing

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>'
📢
Need Help?
If you encounter API issues or need other API requirements, please contact us.
Contact Us

Use Cases

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.

Related operations

Guides

View Subscription Plans →