Skip to main content

City Suggest Autocomplete API

URL​

GET https://api.magicrail.io/cities/autosuggest

Description​

Provide real-time city suggestions based on partial user input. The City Suggest Autocomplete API dynamically suggests city names as the user types, ranking exact matches higher while supporting partial matches.

Authentication​

Bearer Token required.

Headers​

Ensure these headers are included in the request.

  • Content-Type: application/json
  • Authorization: Bearer TOKEN

Query Parameters​

  • q: The partial city name to search for.

Success Response​

Description of a successful attempt to retrieve city suggestions.

  • 🟢 200 OK: Successfully retrieved city suggestions.

Error Responses​

Descriptions of common error responses.

  • 🔴 400 Bad Request: Query parameter "q" is missing or invalid.
  • 🔴 403 Forbidden: Permission denied to access the resource.
  • 🔴 404 Not Found: No matching cities found.
  • 🔴 500 Internal Server Error: Internal server error.

Example Call and Response​

An example showing how to make a request and an example response.

Example Call:

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/cities/autosuggest?q=Winter"

Example Response:

[
  {
    "name": "Winter Garden",
    "state_code": "FL",
    "state_name": "Florida",
    "country_code": "US",
    "country_name": "United States",
    "latitude": "28.56528000",
    "longitude": "-81.58618000",
    "version": "1.0.0"
  },
  {
    "name": "Winter Haven",
    "state_code": "FL",
    "state_name": "Florida",
    "country_code": "US",
    "country_name": "United States",
    "latitude": "28.022243",
    "longitude": "-81.732857",
    "version": "1.0.0"
  }
]