Foursquare Search API

openapi: 3.1.0
info:
  title: Foursquare Places Ask Search API
  description: The Foursquare Places API provides global access to over 100 million points of interest (POI) for place search, details, autocomplete, geotagging (Place Snap), place matching, natural-language Ask search, and photos/tips. All requests target the current host https://places-api.foursquare.com, authenticate with a Service Key as a Bearer token, and must send the X-Places-Api-Version header. This OpenAPI describes the most commonly used endpoints; refer to the official documentation for the complete and authoritative reference.
  version: '2025-06-17'
  contact:
    name: Foursquare Developer Support
    url: https://docs.foursquare.com/
  license:
    name: Foursquare Developer Terms of Service
    url: https://foursquare.com/legal/api/platformpolicy
servers:
- url: https://places-api.foursquare.com
  description: Foursquare Places API (current)
security:
- serviceKey: []
tags:
- name: Search
  description: Find and explore places
paths:
  /places/search:
    get:
      tags:
      - Search
      summary: Search For Places
      description: Find places that match a query, location, category, chain, price, or radius. Returns a paged list of places ordered by the chosen sort.
      operationId: searchPlaces
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - in: query
        name: query
        schema:
          type: string
        description: Free-text search term (e.g., "coffee").
      - in: query
        name: ll
        schema:
          type: string
        description: Latitude,longitude pair (e.g., "40.7128,-74.0060").
      - in: query
        name: near
        schema:
          type: string
        description: Geocodable text location (e.g., "New York, NY").
      - in: query
        name: radius
        schema:
          type: integer
          maximum: 100000
        description: Search radius in meters (0-100000).
      - in: query
        name: ne
        schema:
          type: string
        description: Northeast corner of a bounding box (lat,lng).
      - in: query
        name: sw
        schema:
          type: string
        description: Southwest corner of a bounding box (lat,lng).
      - in: query
        name: fsq_category_ids
        schema:
          type: string
        description: Comma-separated Foursquare category ids.
      - in: query
        name: fsq_chain_ids
        schema:
          type: string
        description: Comma-separated Foursquare chain ids to include.
      - in: query
        name: exclude_fsq_chain_ids
        schema:
          type: string
        description: Comma-separated Foursquare chain ids to exclude.
      - in: query
        name: exclude_all_chains
        schema:
          type: boolean
        description: Return only non-chain (independent) places.
      - in: query
        name: min_price
        schema:
          type: integer
          minimum: 1
          maximum: 4
        description: Minimum price tier (1-4).
      - in: query
        name: max_price
        schema:
          type: integer
          minimum: 1
          maximum: 4
        description: Maximum price tier (1-4).
      - in: query
        name: open_now
        schema:
          type: boolean
        description: Restrict to places currently open.
      - in: query
        name: open_at
        schema:
          type: string
        description: Restrict to places open at a time in DOWTHHMM format (e.g., "1T2130").
      - in: query
        name: fields
        schema:
          type: string
        description: Comma-separated list of fields to include in each result.
      - in: query
        name: limit
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 50
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - RELEVANCE
          - RATING
          - DISTANCE
          - POPULARITY
      - in: query
        name: tel_format
        schema:
          type: string
          enum:
          - NATIONAL
          - E164
      responses:
        '200':
          description: A page of matching places.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceSearchResponse'
components:
  schemas:
    Tip:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        text:
          type: string
    Photo:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        prefix:
          type: string
        suffix:
          type: string
        width:
          type: integer
        height:
          type: integer
    Place:
      type: object
      properties:
        fsq_place_id:
          type: string
        name:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        location:
          type: object
          properties:
            address:
              type: string
            locality:
              type: string
            region:
              type: string
            postcode:
              type: string
            admin_region:
              type: string
            post_town:
              type: string
            po_box:
              type: string
            country:
              type: string
            formatted_address:
              type: string
        categories:
          type: array
          items:
            type: object
            properties:
              fsq_category_id:
                type: string
              name:
                type: string
              short_name:
                type: string
              plural_name:
                type: string
              icon:
                type: object
                properties:
                  prefix:
                    type: string
                  suffix:
                    type: string
        chains:
          type: array
          items:
            type: object
            properties:
              fsq_chain_id:
                type: string
              name:
                type: string
        distance:
          type: integer
        rating:
          type: number
        price:
          type: integer
          minimum: 1
          maximum: 4
        popularity:
          type: number
        verified:
          type: boolean
        date_closed:
          type: string
        tel:
          type: string
        email:
          type: string
        website:
          type: string
        social_media:
          type: object
          properties:
            facebook_id:
              type: string
            instagram:
              type: string
            twitter:
              type: string
        hours:
          type: object
          properties:
            display:
              type: string
            is_local_holiday:
              type: boolean
            open_now:
              type: boolean
        attributes:
          type: object
          properties:
            restroom:
              type: string
            outdoor_seating:
              type: string
            atm:
              type: string
            parking:
              type: object
            wifi:
              type: string
            delivery:
              type: string
            reservations:
              type: string
            credit_cards:
              type: object
        tastes:
          type: array
          items:
            type: string
        stats:
          type: object
          properties:
            total_photos:
              type: integer
            total_ratings:
              type: integer
            total_tips:
              type: integer
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
        tips:
          type: array
          items:
            $ref: '#/components/schemas/Tip'
    PlaceSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Place'
        context:
          type: object
          properties:
            geo_bounds:
              type: object
  parameters:
    ApiVersion:
      in: header
      name: X-Places-Api-Version
      required: true
      description: Dated Places API version (e.g., "2025-06-17").
      schema:
        type: string
        default: '2025-06-17'
  securitySchemes:
    serviceKey:
      type: http
      scheme: bearer
      description: 'Service Key passed as a Bearer token in the Authorization header ("Authorization: Bearer <service-key>").'