openapi: 3.1.0
info:
  title: Foursquare Places Ask Match 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: Match
  description: Match an external POI record to a Foursquare place
paths:
  /places/match:
    get:
      tags:
      - Match
      summary: Match A Place
      description: Match an external POI record (name + address) to the canonical Foursquare place, returning the fsq_place_id and a match_score.
      operationId: matchPlace
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - in: query
        name: name
        required: true
        schema:
          type: string
        description: Name of the place to match.
      - in: query
        name: address
        required: true
        schema:
          type: string
        description: Street address (e.g., "1060 W Addison St").
      - in: query
        name: city
        required: true
        schema:
          type: string
        description: City or locality.
      - in: query
        name: state
        schema:
          type: string
        description: State or region.
      - in: query
        name: postal_code
        schema:
          type: string
      - in: query
        name: cc
        required: true
        schema:
          type: string
        description: ISO 3166-1 alpha-2 country code (e.g., "US").
      - in: query
        name: ll
        schema:
          type: string
        description: Latitude,longitude pair to disambiguate the match.
      - in: query
        name: fields
        schema:
          type: string
      responses:
        '200':
          description: A matched place with confidence score.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceMatchResponse'
components:
  schemas:
    Tip:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        text:
          type: string
    PlaceMatchResponse:
      type: object
      properties:
        place:
          allOf:
          - $ref: '#/components/schemas/Place'
          - type: object
            properties:
              match_score:
                type: number
                minimum: 0
                maximum: 1
                description: Confidence of the match (0-1; higher is stronger).
    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'
  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>").'