Search for Autocomplete

Public Beta Feature

This documentation covers a feature currently in Public Beta. Access is available to anyone interested in building personalized experiences for their end-users.

This feature is subject to the Personalization API (Self-Service) Public Beta End user License Agreement.

Parameters

• version
  string (required)

The API version date as documented here; e.g. 20231010

• query
  string (required)

A search term to be applied against titles.

• ll
  string

The latitude/longitude around which to retrieve place information. This must be specified as latitude,longitude (e.g., ll=41.8781,-87.6298).

• radius
  string

Sets a radius distance (in meters) used to define an area to bias search results. The maximum allowed radius is 100,000 meters. Radius can be used in combination with ll or ip biased geolocation only. By using radius, global search results will be omitted.

• near
  string

A string naming a locality in the world (e.g., "Chicago, IL"). If the value is not geocodable, returns an error.

• ne
  string

The latitude/longitude representing the north/east points of a rectangle. Must be used with sw parameter to specify a rectangular search box. Global search results will be omitted.

• sw
  string

The latitude/longitude representing the south/west points of a rectangle. Must be used with ne parameter to specify a rectangular search box. Global search results will be omitted.

Autocomplete Results

• meta

  • code: integer Defaults to 0
  • requestId: string The unique identifier for the API request.

• notifications: array of objects

  • item: object
    • unreadCount: integer The unread count associated with the autocomplete request.

• response: object

  • groups: array of objects
    • isPlaceholderGroup: boolean Defaults to true.
    • items: array of objects
      • text: string Autocomplete response text.
      • id: string
      • entities: array of objects
        • indices: array of integers
      • type: string
        Type of entities for items in the response.

Example Request

curl --request GET \
     --url https://api.foursquare.com/v2/search/autocomplete \
     --header 'accept: application/json'

Example Response

{
  "meta": {
    "code": 200,
    "requestId": "651312eda774726235afae21"
  },
  "notifications": [
    {
      "type": "notificationTray",
      "item": {
        "unreadCount": 3
      }
    },
    {
      "type": "unconfirmed",
      "item": {
        "unreadCount": 0
      }
    }
  ],
  "response": {
    "groups": [
      {
        "type": "unified",
        "isPlaceholderGroup": false,
        "items": [
          {
            "id": "651312ed897ae12f26abfcf5",
            "entities": [
              {
                "indices": [0, 3],
                "type": "autocompleteMatch"
              }
            ],
            "text": "Coffee",
            "type": "query",
            "object": {
              "querystring": "Coffee",
              "icon": {
                "prefix": "https://irs1.4sqi.net/img/general/cap/",
                "sizes": [30, 45, 60, 90, 120],
                "name": "/dialpad_coffee_20180129.png"
              }
            }
          }
        ]
      }
    ],
    "requestid": "651312eda774726235afae21"
  }
}