foursquare

foursquare#

Description#

Plugin to interact with the Foursquare Places API.

It also raises events when a new check-in occurs on the user’s account.

In order to enable the Foursquare API on your account you need to:

  • Create a new app on the Foursquare developers website.

  • Copy the client_id and client_secret.

  • Add a redirect URL. It must point to a valid IP/hostname with a web server running, even if it runs

    locally. You can also use the local URL of the platypush web server - e.g. http://192.168.1.2:8008/.

  • Open the following URL:

    https://foursquare.com/oauth2/authenticate?client_id=CLIENT_ID&response_type=token&redirect_uri=REDIRECT_URI. Replace CLIENT_ID and REDIRECT_URI with the parameters from your app.

  • Allow the application. You will be redirected to the URL you provided. Copy the access_token provided in

    the URL.

Configuration#

foursquare:
  # [Required]
  # The access token to use to authenticate to the Foursquare API.
  access_token:   # type=str

  # [Optional]
  # Poll interval in seconds to check for new check-ins (default: 120).
  # Set to 0 or ``None`` to disable polling of new check-ins.
  # poll_interval: 120  # type=float

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Triggered events#

Actions#

Module reference#

class platypush.plugins.foursquare.FoursquarePlugin(access_token: str, poll_interval: float = 120, **kwargs)[source]#

Bases: RunnablePlugin

Plugin to interact with the Foursquare Places API.

It also raises events when a new check-in occurs on the user’s account.

In order to enable the Foursquare API on your account you need to:

  • Create a new app on the Foursquare developers website.

  • Copy the client_id and client_secret.

  • Add a redirect URL. It must point to a valid IP/hostname with a web server running, even if it runs

    locally. You can also use the local URL of the platypush web server - e.g. http://192.168.1.2:8008/.

  • Open the following URL:

    https://foursquare.com/oauth2/authenticate?client_id=CLIENT_ID&response_type=token&redirect_uri=REDIRECT_URI. Replace CLIENT_ID and REDIRECT_URI with the parameters from your app.

  • Allow the application. You will be redirected to the URL you provided. Copy the access_token provided in

    the URL.

__init__(access_token: str, poll_interval: float = 120, **kwargs)[source]#
Parameters:

  • poll_interval – Poll interval in seconds to check for new check-ins (default: 120). Set to 0 or None to disable polling of new check-ins.

  • access_token – The access token to use to authenticate to the Foursquare API.

checkin(venue_id: str, shout: str | None = None) → Dict[str, Any][source]#

Create a new check-in.

Parameters:

  • venue_id – ID of the venue to check-in.

  • shout – Add a custom message to the check-in.

Returns:

Foursquare API response.

explore(latitude: float | None = None, longitude: float | None = None, near: str | None = None, query: str | None = None, limit: int | None = None, categories: List[str] | None = None, radius: int | None = None) → List[Dict[str, Any]][source]#

Explore venues around a location.

Parameters:

  • latitude – Search near this latitude. Note either latitude, longitude or near should be provided.

  • longitude – Search near this latitude. Note either latitude, longitude or near should be provided.

  • near – Search near this place (e.g. “Chicago, IL” or “Amsterdam, NL”). Note either latitude, longitude or near should be provided.

  • query – Search query (e.g. “coffee shops” or “restaurants”).

  • limit – Maximum number of results.

  • categories – List of category IDs to be searched.

  • radius – Search radius in meters.

Returns:

A list of venues, as returned by the Foursquare API.

get_checkins(limit: int = 20, offset: int = 0) → List[Dict[str, Any]][source]#

Get the list of check-ins of the current user.

Parameters:

  • limit – Maximum number of check-ins to retrieve (default: 20).

  • offset – Offset to start retrieving check-ins from (default: 0).

Returns:

A list of checkins, as returned by the Foursquare API.

search(latitude: float | None = None, longitude: float | None = None, near: str | None = None, query: str | None = None, limit: int | None = None, url: str | None = None, categories: List[str] | None = None, radius: int | None = None) → List[Dict[str, Any]][source]#

Search for venues.

Parameters:

  • latitude – Search near this latitude. Note either latitude, longitude or near should be provided.

  • longitude – Search near this latitude. Note either latitude, longitude or near should be provided.

  • near – Search near this place (e.g. “Chicago, IL” or “Amsterdam, NL”). Note either latitude, longitude or near should be provided.

  • query – Search query (e.g. “coffee shops” or “restaurants”).

  • limit – Maximum number of results.

  • url – A 3rd-party URL associated to the venue to be searched.

  • categories –

    List of category IDs to be searched.

  • radius – Search radius in meters.

Returns:

A list of venues, as returned by the Foursquare API.

trending(latitude: float | None = None, longitude: float | None = None, near: str | None = None, limit: int | None = None, radius: int | None = None) → List[Dict[str, Any]][source]#

Get the trending venues around a location.

Parameters:

  • latitude – Search near this latitude. Note either latitude, longitude or near should be provided.

  • longitude – Search near this latitude. Note either latitude, longitude or near should be provided.

  • near – Search near this place (e.g. “Chicago, IL” or “Amsterdam, NL”). Note either latitude, longitude or near should be provided.

  • limit – Maximum number of results.

  • radius – Search radius in meters.

Returns:

A list of venues, as returned by the Foursquare API.

Platypush documentation