Search Geo 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.

API 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.

Response Structure

• meta
  object
  Object containing additional information about the response from a geo autocomplete search, including status code, unique request identifier, and any notifications.

  • code
    integer
    Defaults to 0
    Response status code for the autocomplete search results.
  • requestId
    string
    Unique identifier for the API request.
  • notifications
    array of objects
    Array of notification objects containing information about the returned results.
    • item
      object
      Array of notification objects containing the type and number of unread items for a specific search query.
      • type
        string
        The type of notification for a successful response to a geoautocomplete search.

• response
  object
  Response object containing the retrieved data for a geoautocomplete search query.

  • results
    array of objects
    Array of venue objects containing information about venues that match the user's search query.
    • bounds
      object
      Properties for the geographical autocomplete search results, indicating the boundary coordinates for each item.
      • ne
        object
        Bounding box for the northeast corner.
      • sw
        object
        Bounding box for the southwest corner.
    • entities
      array of objects
      Array of entities returned by the geoautocomplete search endpoint.
      • indices
        array of integers
        Indices of entities mentioned in the results of a geo-autocomplete search.
      • type
        string
        The type of entities found in the results of a successful geoautocomplete search.
    • geoId
      integer
      Defaults to 0
      Unique identifier for the geographic location returned in the search results.
    • ll
      object
      The latitude and longitude coordinates for the items returned in the response for the geoautocomplete search.
      • text
        string
        The text of the autocomplete results for a geo search.
      • displayText
        string
        Display text for the results of a geoautocomplete search.

Example CURL Request

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

Sample Response

{
  "meta": {
    "code": 200,
    "requestId": "65131337cf4b6231c7927e08"
  },
  "notifications": [
    {
      "type": "notificationTray",
      "item": {
        "unreadCount": 3
      }
    },
    {
      "type": "unconfirmed",
      "item": {
        "unreadCount": 0
      }
    }
  ],
  "response": {
    "results": [
      {
        "entities": [
          {
            "indices": [0, 3],
            "type": "autocompleteMatch"
          }
        ],
        "text": "Coffeen, IL, United States",
        "displayText": "Coffeen, IL, United States",
        "geoId": 72057594042164060,
        "ll": {
          "lat": 39.08921,
          "lng": -89.39064
        },
        "bounds": {
          "ne": {
            "lat": 39.096855999999995,
            "lng": -89.37964099999999
          },
          "sw": {
            "lat": 39.077942,
            "lng": -89.401917
          }
        },
        "type": "geocoder"
      },
      {
        "entities": [
          {
            "indices": [0, 3],
            "type": "autocompleteMatch"
          }
        ],
        "text": "Coffeyville, KS, United States",
        "displayText": "Coffeyville, KS, United States",
        "geoId": 72057594042197730,
        "ll": {
          "lat": 37.0373,
          "lng": -95.61637
        },
        "bounds": {
          "ne": {
            "lat": 37.100463,
            "lng": -95.57616399999999
          },
          "sw": {
            "lat": 37.007073,
            "lng": -95.681896
          }
        },
        "type": "geocoder"
      },
      {
        "entities": [
          {
            "indices": [0, 3],
            "type": "autocompleteMatch"
          }
        ],
        "text": "Coffs Harbour, NSW, Australia",
        "displayText": "Coffs Harbour, NSW, Australia",
        "geoId": 72057594040099020,
        "ll": {
          "lat": -30.29626,
          "lng": 153.11351
        },
        "bounds": {
          "ne": {
            "lat": -30.261617006500018,
            "lng": 153.15457222400002
          },
          "sw": {
            "lat": -30.32083602450001,
            "lng": 153.082098016
          }
        },
        "type": "geocoder"
      },
      {
        "text": "UMQ Coffee | قهوة عـُمق",
        "displayText": "UMQ Coffee | قهوة عـُمق",
        "venueId": "5e00face028e6200084601aa",
        "venuePhoto": {
          "id": "635388dfce69400ab9175ad5",
          "createdAt": 1666418911,
          "prefix": "https://fastly.4sqi.net/img/general/",
          "suffix": "/1372354206_k4atk2sDW76-FlC_uTPlYv5512_lpNO-uCYfbMBDXg0.jpg",
          "width": 1440,
          "height": 1440,
          "visibility": "public"
        },
        "venueCategory": {
          "id": "4bf58dd8d48988d1e0931735",
          "name": "Coffee Shop",
          "pluralName": "Coffee Shops",
          "shortName": "Coffee Shop",
          "icon": {
            "prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
            "suffix": ".png"
          }
        },
        "ll": {
          "lat": 26.397691,
          "lng": 50.092241
        },
        "type": "near_venue"
      }
    ]
  }
}