Response Fields

Response fields define the returnable metadata of the FSQ Places API. This data will be returned when requesting a Places Search or Place Details call. This page lists all place data fields and their groupings.

Types of Returnable :

  1. Places Core Data
  2. Places Rich Data
  3. Address Data

Places Core Data

FieldDescription
fsq_idA unique identifier for a FSQ Place (formerly known as Venue ID).
nameThe best known name for the FSQ Place.
geocodesSet of geocodes (latitude, longitude) for the Place. The primary coordinates are identified by the main latitude and longitude.

Where available, other coordinates may include:
- roof
- drop_off
- front_door
- road
locationAn object containing none, some, or all of the following fields:
- address
- address_extended
- locality
- dma
- region
- postcode
- country
- admin_region
- post_town
- po_box
- cross_street
- formatted_address
- census_block: populated only for Places within the United States, in all other countries it will be null.

NOTE: For the Autocomplete and Address Data APIs, the location object data is populated by the verified address data provided by Loqate.

View Loqate's Full Coverage List
categoriesAn array, possibly empty, of categories that describe the FSQ Place. Included subfields: id (Category ID), name (Category Label), and icon (Category's Icon).

View the list of FSQ Categories
chainsAn array, possibly empty, of chains that the FSQ Place belongs to. Included subfields: id (Chain ID) and name (Chain Name).

View the list of FSQ Chains
related_placesAn object containing the information for Places related to the FSQ Place. Included subfields: parent and children. Not all FSQ Places will have parent or children relationships.

Some Children Place responses may not show a fsq_id. This indicates that Foursquare does not have enough data inputs to mark the Child Place as an official Place.

Example:
parent = Los Angeles International Airport
children = Terminal 1, Terminal 2, Terminal 3...
timezoneA string that denotes the region representing the FSQ Place's timezone.
distanceThe calculated distance (in meters) from the provided location (i.e. ll + radius OR near OR ne + sw) in the API call. This field will only be returned by the Place Search endpoint.
link The URL associated with the corresponding Places Detail API call for the returned Place.
closed_bucketProbability that a POI is Open/Closed.

- VeryLikelyOpen, VeryLikelyClosed: 95% Confidence that a POI is Open/Closed respectively

- LikelyOpen, LikelyClosed: 80% Confidence that a POI identified as LikelyOpen/VeryLikelyOpen is Open . Similarly, 80% Confidence that a POI marked as LikelyClosed/VeryLikelyClosed is Closed

back to top


Places Rich Data

FieldDescription
descriptionA general description of the FSQ Place. Typically provided by the owner/claimant of the FSQ Place and/or updated by City Guide Superusers.
telThe best known telephone number, with local formatting.
faxThe best known fax number, with local formatting.
emailThe primary contact email address for the FSQ Place.
websiteThe official website for the FSQ Place.
social_mediaAn object containing a FSQ Place's social media identifiers. Included subfields: facebook_id, instagram, and twitter. Not all FSQ Places will have all subfields.
verifiedA boolean that indicates whether or not the FSQ Place has been claimed.
hoursAn array containing the regular hours of operation, is_local_holiday, open_now, and a formatted display string.

regular hours contain subfields: day (1 = Monday, 2 = Tuesday, 7 = Sunday) and open/close (24-hour time).
hours_popularAn array containing the hours during the week when a FSQ Place is most often visited. This place must have a minimum number of check-ins to be considered for the calculation.

Similar to hours, this field contains subfields: day (1 = Monday, 2 = Tuesday, 7 = Sunday) and open/close (24-hour time).
ratingA numerical rating (from 0.0 to 10.0) of the FSQ Place, based on user votes, likes/dislikes, tips sentiment, and visit data. Not all FSQ Places will have a rating.

NOTE: v3 does not include the following mapped ratings to colors as could be found in v2:
- 0.0 = LightMediumGrey (#C7CDCF)
- 0.0 <> 4.0 = Red (#E6092C)
- 4.0 <> 5.0 = DarkOrange (#FF6701)
- 5.0 <> 6.0 = Orange (#FF9600)
- 6.0 <> 7.0 = Yellow (#FFC800)
- 7.0 <> 8.0 = LightGreen (#C5DE35)
- 8.0 <> 9.0 = Green (#73CF42)
- 9.0 + = DarkGreen (#00B551)
statsAn object containing counts of photos, ratings, and tips. Included subfields: total_photos, total_ratings, and total_tips.
popularityA measure of the FSQ Place's popularity, by foot traffic. This score is on a 0 to 1 scale and uses a 6-month span of Place visits for a given geographic area.
priceA numerical value (from 1 to 4) that best describes the pricing tier of the FSQ Place, based on known prices for menu items and other offerings.

Values include:
- 1 = Cheap
- 2 = Moderate
- 3 = Expensive
- 4 = Very Expensive.
menuA linked menu for the FSQ Place.
date_closedThe recorded date when the FSQ Place was marked as permanently closed in Foursquare's databases. This does not necessarily indicate the Place was actually closed on this date.
photosAn array of objects containing the following subfields:
- id
- created_at
- classifications
- prefix
- suffix
- width
- height.

For more information, see our Photos Guide
tipsAn array containing the following subfields: created_at and text.
tastesAn array of up to 25 tastes that best describe the FSQ Place.
features A list of boolean tags that help to describe services and additional metadata offered by the Place (e.g. takes_reservations: true)

For a full list of tags, see Places Tags.
store_idThe unique ID assigned to a venue in order to differentiate it from other stores within the same chain.
venue_reality_bucketThis attribute represents how “real” Foursquare believes a venue to be. As venues can be submitted directly by users, Foursquare uses a proprietary algorithm to assess real venues (public places like a popular restaurant, store, concert venue, etc) vs a private or nonexistent venue. Foursquare’s Venue Reality algorithm uses a combination of explicit and implicit signals (examples include number of searches on Foursquare, number of photos/tips submitted, number of check-ins, etc) to bucket venues with an output of Low, Medium, High, VeryHigh

back to top


Address Data

FieldDescription
location An object containing none, some, or all of the following fields: address, address_extended, locality, dma, region, postcode, country, admin_region, post_town, po_box, and cross_street.
geocodes Set of geocodes (latitude, longitude) for the Place. The primary coordinates are identified by the main latitude and longitude.

Where available, other coordinates may include: roof, drop_off, front_door, and road.

back to top


Sample Places Data Response

{
  "results": [
    {
      "fsq_id": "string",
      "categories": [
        {
          "id": 0,
          "name": "string",
          "icon": {
            "id": "string",
            "created_at": "2023-10-11T16:32:04.439Z",
            "prefix": "string",
            "suffix": "string",
            "width": 0,
            "height": 0,
            "classifications": [
              "string"
            ],
            "tip": {
              "id": "string",
              "created_at": "2023-10-11T16:32:04.439Z",
              "text": "string",
              "url": "string",
              "lang": "string",
              "agree_count": 0,
              "disagree_count": 0
            }
          }
        }
      ],
      "chains": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "closed_bucket": "string",
      "date_closed": "2023-10-11",
      "description": "string",
      "distance": 0,
      "email": "string",
      "fax": "string",
      "features": {
        "payment": {
          "credit_cards": {
            "accepts_credit_cards": {},
            "amex": {},
            "discover": {},
            "visa": {},
            "diners_club": {},
            "master_card": {},
            "union_pay": {}
          },
          "digital_wallet": {
            "accepts_nfc": {}
          }
        },
        "food_and_drink": {
          "alcohol": {
            "bar_service": {},
            "beer": {},
            "byo": {},
            "cocktails": {},
            "full_bar": {},
            "wine": {}
          },
          "meals": {
            "bar_snacks": {},
            "breakfast": {},
            "brunch": {},
            "lunch": {},
            "happy_hour": {},
            "dessert": {},
            "dinner": {},
            "tasting_menu": {}
          }
        },
        "services": {
          "delivery": {},
          "takeout": {},
          "drive_through": {},
          "dine_in": {
            "reservations": {},
            "online_reservations": {},
            "groups_only_reservations": {},
            "essential_reservations": {}
          }
        },
        "amenities": {
          "restroom": {},
          "smoking": {},
          "jukebox": {},
          "music": {},
          "live_music": {},
          "private_room": {},
          "outdoor_seating": {},
          "tvs": {},
          "atm": {},
          "coat_check": {},
          "wheelchair_accessible": {},
          "parking": {
            "parking": {},
            "street_parking": {},
            "valet_parking": {},
            "public_lot": {},
            "private_lot": {}
          },
          "sit_down_dining": {},
          "wifi": "string"
        },
        "attributes": {
          "business_meeting": "string",
          "clean": "string",
          "crowded": "string",
          "dates_popular": "string",
          "dressy": "string",
          "families_popular": "string",
          "gluten_free_diet": "string",
          "good_for_dogs": "string",
          "groups_popular": "string",
          "healthy_diet": "string",
          "late_night": "string",
          "noisy": "string",
          "quick_bite": "string",
          "romantic": "string",
          "service_quality": "string",
          "singles_popular": "string",
          "special_occasion": "string",
          "trendy": "string",
          "value_for_money": "string",
          "vegan_diet": "string",
          "vegetarian_diet": "string"
        }
      },
      "geocodes": {
        "drop_off": {
          "latitude": 0,
          "longitude": 0
        },
        "front_door": {
          "latitude": 0,
          "longitude": 0
        },
        "main": {
          "latitude": 0,
          "longitude": 0
        },
        "road": {
          "latitude": 0,
          "longitude": 0
        },
        "roof": {
          "latitude": 0,
          "longitude": 0
        }
      },
      "hours": {
        "display": "string",
        "is_local_holiday": true,
        "open_now": true,
        "regular": [
          {
            "close": "string",
            "day": 0,
            "open": "string"
          }
        ]
      },
      "hours_popular": [
        {
          "close": "string",
          "day": 0,
          "open": "string"
        }
      ],
      "link": "string",
      "location": {
        "address": "string",
        "address_extended": "string",
        "admin_region": "string",
        "census_block": "string",
        "country": "string",
        "cross_street": "string",
        "dma": "string",
        "formatted_address": "string",
        "locality": "string",
        "neighborhood": [
          "string"
        ],
        "po_box": "string",
        "post_town": "string",
        "postcode": "string",
        "region": "string"
      },
      "menu": "string",
      "name": "string",
      "photos": [
        {
          "id": "string",
          "created_at": "2023-10-11T16:32:04.439Z",
          "prefix": "string",
          "suffix": "string",
          "width": 0,
          "height": 0,
          "classifications": [
            "string"
          ],
          "tip": {
            "id": "string",
            "created_at": "2023-10-11T16:32:04.439Z",
            "text": "string",
            "url": "string",
            "lang": "string",
            "agree_count": 0,
            "disagree_count": 0
          }
        }
      ],
      "popularity": 0,
      "price": 0,
      "rating": 0,
      "related_places": {},
      "social_media": {
        "facebook_id": "string",
        "instagram": "string",
        "twitter": "string"
      },
      "stats": {
        "total_photos": 0,
        "total_ratings": 0,
        "total_tips": 0
      },
      "store_id": "string",
      "tastes": [
        "string"
      ],
      "tel": "string",
      "timezone": "string",
      "tips": [
        {
          "id": "string",
          "created_at": "2023-10-11T16:32:04.439Z",
          "text": "string",
          "url": "string",
          "lang": "string",
          "agree_count": 0,
          "disagree_count": 0
        }
      ],
      "venue_reality_bucket": "string", 
      "verified": true,
      "website": "string"
    }
  ],
  "context": {
    "geo_bounds": {
      "circle": {
        "center": {
          "latitude": 0,
          "longitude": 0
        },
        "radius": 0
      }
    }
  }
}

For assistance and related questions, reach out to our team for support.