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

Field

Description

fsq_id

A unique identifier for a FSQ Place (formerly known as Venue ID).

name

The best known name for the FSQ Place.

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
  • road

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
  • 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

categories

An 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

chains

An 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_places

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

Example:
parent = Los Angeles International Airport
children = Terminal 1, Terminal 2, Terminal 3...

timezone

A string that denotes the region representing the FSQ Place's timezone.

distance

The 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

Field

Description

description

A general description of the FSQ Place. Typically provided by the owner/claimant of the FSQ Place and/or updated by City Guide Superusers.

tel

The best known telephone number, with local formatting.

fax

The best known fax number, with local formatting.

email

The primary contact email address for the FSQ Place.

website

The official website for the FSQ Place.

social_media

An object containing a FSQ Place's social media identifiers. Included subfields: facebook_id, instagram, and twitter. Not all FSQ Places will have all subfields.

verified

A boolean that indicates whether or not the FSQ Place has been claimed.

hours

An 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_popular

An 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).

rating

A 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)

stats

An object containing counts of photos, ratings, and tips. Included subfields: total_photos, total_ratings, and total_tips.

popularity

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

price

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

menu

A linked menu for the FSQ Place.

date_closed

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

photos

An array containing the following subfields:

  • id
  • created_at
  • classifications
  • prefix
  • suffix
  • width
  • height.

For more information, see our Photos Guide

tips

An array containing the following subfields: created_at and text.

tastes

An 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

Field

Description

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.