openapi: 3.1.0
info:
  title: Foursquare Places Ask 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: Ask
  description: Natural-language place search with justifications
paths:
  /places/ask:
    get:
      tags:
      - Ask
      summary: Ask For Places
      description: Natural-language place search. Returns ranked places that answer a free-form question, each with justifications explaining the match.
      operationId: askPlaces
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - in: query
        name: query
        required: true
        schema:
          type: string
        description: Natural language query (e.g., "cheap cafes in Williamsburg").
      - in: query
        name: ll
        schema:
          type: string
        description: Latitude,longitude pair for "near me" intent.
      - in: query
        name: location
        schema:
          type: string
        description: Geocodable locality string (e.g., "Chicago, IL").
      - in: query
        name: context
        schema:
          type: string
        description: Query-specific personalization context (e.g., "traveling with kids").
      - in: query
        name: fields
        schema:
          type: string
      responses:
        '200':
          description: Ranked, justified places answering the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
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'
    AskResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              justifications:
                type: array
                items:
                  type: string
                description: Human-readable reasons the place matches the query.
              place:
                $ref: '#/components/schemas/Place'
  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>").'