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. POI - Core Data
  2. POI - Rich Data
  3. Address Data

POI 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 POI. 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
- neighborhood
- 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 POIs related to the FSQ Place. Included subfields: parent and children. Not all FSQ Places will have parent or children relationships.

Some Children POI responses may not show a fsq_id. This indicates that Foursquare does not have enough data inputs to mark the Child POI 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 POI.

back to top


POI 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, seasonal hours (with start/end dates), is_local_holiday, open_now, and a formatted display string.

Both regular/seasonal 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 POI 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 POI was actually closed on this date.
photosAn array 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 POI (e.g. takes_reservations: true)

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, neighborhood, po_box, and cross_street.
geocodes Set of geocodes (latitude, longitude) for the POI. 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 POI Data Response

{
  "results": [
    {
      "fsq_id": "string",
      "categories": [
        {
          "id": 0,
          "name": "string",
          "icon": {
            "id": "string",
            "created_at": "2022-03-22T18:52:03.724Z",
            "prefix": "string",
            "suffix": "string",
            "width": 0,
            "height": 0,
            "classifications": [
              "string"
            ],
            "tip": {
              "id": "string",
              "created_at": "2022-03-22T18:52:03.724Z",
              "text": "string",
              "url": "string",
              "lang": "string",
              "agree_count": 0,
              "disagree_count": 0
            }
          }
        }
      ],
      "census_block_id": "string",
      "chains": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "date_closed": "2022-03-22",
      "description": "string",
      "distance": 0,
      "email": "string",
      "fax": "string",
      "features": {
        "payment": {
          "credit_cards": {
            "accepts_credit_cards": {},
            "discover": {},
            "visa": {},
            "diners_club": {},
            "master_card": {}
          },
          "digital_wallet": {
            "accepts_nfc": {}
          }
        },
        "food_and_drink": {
          "alcohol": {
            "beer": {},
            "byo": {},
            "cocktails": {},
            "full_bar": {},
            "wine": {}
          },
          "meals": {
            "breakfast": {},
            "brunch": {},
            "lunch": {},
            "happy_hour": {},
            "dessert": {},
            "dinner": {}
          }
        },
        "services": {
          "delivery": {},
          "takeout": {},
          "drive_through": {},
          "dine_in": {
            "reservations": {},
            "online_reservations": {},
            "groups_only_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": {}
          }
        }
      },
      "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"
          }
        ],
        "seasonal": [
          {
            "closed": true,
            "end_date": "2022-03-22",
            "hours": [
              {
                "close": "string",
                "day": 0,
                "open": "string"
              }
            ],
            "start_date": "2022-03-22"
          }
        ]
      },
      "hours_popular": [
        {
          "close": "string",
          "day": 0,
          "open": "string"
        }
      ],
      "location": {
        "address": "string",
        "address_extended": "string",
        "admin_region": "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": "2022-03-22T18:52:03.724Z",
          "prefix": "string",
          "suffix": "string",
          "width": 0,
          "height": 0,
          "classifications": [
            "string"
          ],
          "tip": {
            "id": "string",
            "created_at": "2022-03-22T18:52:03.724Z",
            "text": "string",
            "url": "string",
            "lang": "string",
            "agree_count": 0,
            "disagree_count": 0
          }
        }
      ],
      "popularity": 0,
      "price": 0,
      "rating": 0,
      "related_places": {
        "children": [
          null
        ]
      },
      "social_media": {
        "facebook_id": "string",
        "instagram": "string",
        "twitter": "string"
      },
      "stats": {
        "total_photos": 0,
        "total_ratings": 0,
        "total_tips": 0
      },
      "tastes": [
        "string"
      ],
      "tel": "string",
      "timezone": "string",
      "tips": [
        {
          "id": "string",
          "created_at": "2022-03-22T18:52:03.724Z",
          "text": "string",
          "url": "string",
          "lang": "string",
          "agree_count": 0,
          "disagree_count": 0
        }
      ],
      "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.