Coveo Backend Coding Challenge

Api exposed on https://oksapvn-coding-challenge.herokuapp.com/suggestions?q=ork&latitude=34.9943&longitude=-81.24202

API

GET {HOST}/suggestion

Params	type	require	description	default value
q	String	true	search string	none
latitude	Double	false	latitude	null
longitude	Double	false	longitude	null
limit	Integer	false	max number of cities in response	5

Requirements

Design a REST API endpoint that provides auto-complete suggestions for large cities.

• The endpoint is exposed at /suggestions
• The partial (or complete) search term is passed as a querystring parameter q
• The caller's location can optionally be supplied via querystring parameters latitude and longitude to help improve relative scores
• The endpoint returns a JSON response with an array of scored suggested matches
  • The suggestions are sorted by descending score
  • Each suggestion has a score between 0 and 1 (inclusive) indicating confidence in the suggestion (1 is most confident)
  • Each suggestion has a name which can be used to disambiguate between similarly named locations
  • Each suggestion has a latitude and longitude

Sample responses

These responses are meant to provide guidance. The exact values can vary based on the data source and scoring algorithm

Near match

GET /suggestions?q=Londo&latitude=43.70011&longitude=-79.4163

{
  "suggestions": [
    {
      "name": "London, ON, Canada",
      "latitude": "42.98339",
      "longitude": "-81.23304",
      "score": 0.9
    },
    {
      "name": "London, OH, USA",
      "latitude": "39.88645",
      "longitude": "-83.44825",
      "score": 0.5
    },
    {
      "name": "London, KY, USA",
      "latitude": "37.12898",
      "longitude": "-84.08326",
      "score": 0.5
    },
    {
      "name": "Londontowne, MD, USA",
      "latitude": "38.93345",
      "longitude": "-76.54941",
      "score": 0.3
    }
  ]
}

No match

GET /suggestions?q=SomeRandomCityInTheMiddleOfNowhere

{
  "suggestions": []
}

References

• Geonames provides city lists Canada and the USA http://download.geonames.org/export/dump/readme.txt