Foursquare API Rules

aid: foursquare:places-rules
name: Foursquare Places API Operational Rules
description: >-
  Operational rules and constraints for working with the Foursquare Places API,
  covering authentication, query parameters, rate limits, attribution, and
  data caching.
modified: '2026-06-02'
rules:
  - id: service-key-required
    title: Service Key Required
    description: >-
      All Places API requests require a Service Key supplied as a Bearer token
      in the Authorization header (Authorization: Bearer <service-key>) against
      the host https://places-api.foursquare.com.
    severity: required
  - id: api-version-header-required
    title: Send The API Version Header
    description: >-
      Every Places API request must include the X-Places-Api-Version header
      with a dated version string (e.g., 2025-06-17). Requests without it are
      rejected or default to an unintended version.
    severity: required
  - id: location-required
    title: Provide Location Context
    description: >-
      Place search and geotagging endpoints require a location signal: a ll
      (lat,lng) pair, a near/location textual locality, or a bounding box
      (ne/sw). Without one, results will be empty or rejected.
    severity: required
  - id: radius-cap
    title: Radius Limit
    description: >-
      Search radius is capped at 100,000 meters. Use category filters and
      sort parameters to narrow results rather than expanding radius.
    severity: required
  - id: limit-cap
    title: Pagination Limit Cap
    description: >-
      The limit parameter is capped at 50 results per page. Use cursor-based
      pagination via the link headers for larger result sets.
    severity: required
  - id: fields-projection
    title: Use Field Projection
    description: >-
      Pass the fields parameter to project only required attributes. Default
      responses are minimal; rich attributes (hours, rating, popularity,
      stats) must be explicitly requested.
    severity: recommended
  - id: attribution
    title: Foursquare Attribution
    description: >-
      Apps using the Places API must display Foursquare attribution per the
      developer terms. Consult the platform policy before publishing.
    severity: required
  - id: caching-policy
    title: Caching Restrictions
    description: >-
      Cached place data must comply with Foursquare developer terms; in
      particular, long-term storage of POI data without periodic refresh is
      restricted.
    severity: required
  - id: rate-limits
    title: Rate Limits
    description: >-
      Plans have request-per-second and per-day limits. Implement
      exponential backoff on HTTP 429 responses and inspect rate-limit
      headers.
    severity: required
  - id: category-ids
    title: Use Category IDs
    description: >-
      Filtering by Foursquare category id is more reliable than free-text
      query and yields better recall and precision; consult the category
      taxonomy.
    severity: recommended
  - id: use-place-id-field
    title: Use fsq_place_id
    description: >-
      The current Places API identifies places with fsq_place_id and category
      nodes with fsq_category_id. The legacy fsq_id / numeric category id
      fields are no longer returned by places-api.foursquare.com.
    severity: required