Foursquare Geotagging API

openapi: 3.1.0
info:
  title: Foursquare Places Ask Geotagging 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: Geotagging
  description: Resolve a coordinate to the most likely place (Place Snap)
paths:
  /geotagging/candidates:
    get:
      tags:
      - Geotagging
      summary: Find Geotagging Candidates
      description: Place Snap. Given a device coordinate (and optional accuracy), return the most likely places the user is currently located at, ordered by likelihood.
      operationId: geotaggingCandidates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - in: query
        name: ll
        schema:
          type: string
        description: Latitude,longitude pair (e.g., "40.74,-74.0").
      - in: query
        name: hacc
        schema:
          type: number
          format: double
        description: Horizontal accuracy radius in meters.
      - in: query
        name: altitude
        schema:
          type: number
          format: double
        description: Altitude in meters above the WGS84 ellipsoid.
      - in: query
        name: query
        schema:
          type: string
        description: Optional string matched against candidate place names.
      - in: query
        name: limit
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 50
      - in: query
        name: fields
        schema:
          type: string
      responses:
        '200':
          description: Candidate places for the supplied location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeotaggingResponse'
components:
  schemas:
    Tip:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        text:
          type: string
    GeotaggingResponse:
      type: object
      properties:
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/Place'
    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>").'