platypush.plugins.foursquare

class platypush.plugins.foursquare.FoursquarePlugin(access_token: str, **kwargs)[source]

Plugin to interact with the Foursquare Places API.

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, **kwargs)[source]
Parameters:access_token
checkin(venue_id: str, latitude: Optional[float] = None, longitude: Optional[float] = None, altitude: Optional[float] = None, latlng_accuracy: Optional[float] = None, altitude_accuracy: Optional[float] = None, shout: Optional[str] = None, broadcast: Optional[List[str]] = None) → Dict[str, Any][source]

Create a new check-in.

Parameters:
  • venue_id – ID of the venue to check-in.
  • latitude – Check-in latitude.
  • longitude – Check-in longitude.
  • altitude – Check-in altitude.
  • latlng_accuracy – Latitude/longitude accuracy in meters.
  • altitude_accuracy – Altitude accuracy in meters.
  • shout – Add a custom message to the check-in.
  • broadcast

    List of Visibility/share types of the check-in. Default: public. Possible values are:

    • private
    • public
    • followers
    • facebook
    • twitter
Returns:

Foursquare API response.

explore(latitude: Optional[float] = None, longitude: Optional[float] = None, altitude: Optional[float] = None, latlng_accuracy: Optional[float] = None, altitude_accuracy: Optional[float] = None, section: Optional[str] = None, near: Optional[str] = None, query: Optional[str] = None, limit: Optional[int] = None, categories: Optional[List[str]] = None, radius: Optional[int] = None, open_now: bool = True, sort_by_distance: Optional[bool] = None, sort_by_popularity: Optional[bool] = None, price: Optional[List[int]] = None, saved: Optional[bool] = 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.
  • altitude – Search near this altitude in meters.
  • latlng_accuracy – Latitude/longitude accuracy in meters.
  • altitude_accuracy – Altitude accuracy in meters.
  • section

    Section to search. Supported values:

    • food
    • drinks
    • coffee
    • shops
    • arts
    • outdoors
    • sights
    • trending
    • nextVenues
  • query – Search query (e.g. “coffee shops” or “restaurants”). The parameter has no effect if section is specified.
  • limit – Maximum number of results.
  • categories – List of ``category IDs <https://developer.foursquare.com/docs/resources/categories>``_ to be searched.
  • radius – Search radius in meters.
  • open_now – Filter by open/not open now.
  • sort_by_distance – Sort by distance.
  • sort_by_popularity – Sort by popularity
  • price – Price ranges, within the range [1,2,3,4].
  • saved – Filter by saved/unsaved venues.
Returns:

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

get_checkins() → List[Dict[str, Any]][source]

Get the list of check-ins of the current user. :return: A list of checkins, as returned by the Foursquare API.

managed() → List[Dict[str, Any]][source]

Get the list of venues managed by the user. :return: A list of venues, as returned by the Foursquare API.

search(latitude: Optional[float] = None, longitude: Optional[float] = None, altitude: Optional[float] = None, latlng_accuracy: Optional[float] = None, altitude_accuracy: Optional[float] = None, near: Optional[str] = None, query: Optional[str] = None, limit: Optional[int] = None, url: Optional[int] = None, categories: Optional[List[str]] = None, radius: Optional[int] = None, sw: Union[Tuple[float], List[float], None] = None, ne: Union[Tuple[float], List[float], 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.
  • altitude – Search near this altitude in meters.
  • latlng_accuracy – Latitude/longitude accuracy in meters.
  • altitude_accuracy – Altitude accuracy in meters.
  • query – Search query (e.g. “coffee shops” or “restaurants”).
  • limit – Maximum number of results.
  • url – Venue URL to search.
  • categories – List of ``category IDs <https://developer.foursquare.com/docs/resources/categories>``_ to be searched.
  • radius – Search radius in meters.
  • sw – South/west boundary box as a [latitude, longitude] pair.
  • ne – North/east boundary box as a [latitude, longitude] pair.
Returns:

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

stats(venue_id: str, start_at: Union[int, float, datetime.datetime, str], end_at: Union[int, float, datetime.datetime, str]) → List[Dict[str, Any]][source]

Get the stats about a venue over a time range. The user must be a manager of that venue.

Parameters:
  • venue_id – Venue ID.
  • start_at – Stats start time. Can be a UNIX timestamp, a datetime object or an ISO format datetime.
  • end_at – Stats end time. Can be a UNIX timestamp, a datetime object or an ISO format datetime.
Returns:

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

time_series(venue_id: Union[str, List[str]], start_at: Union[int, float, datetime.datetime, str], end_at: Union[int, float, datetime.datetime, str]) → List[Dict[str, Any]][source]

Get the visitors stats about one or multiple venues over a time range. The user must be a manager of those venues.

Parameters:
  • venue_id – Venue ID or list of IDs to get the stats for.
  • start_at – Stats start time. Can be a UNIX timestamp, a datetime object or an ISO format datetime.
  • end_at – Stats end time. Can be a UNIX timestamp, a datetime object or an ISO format datetime.
Returns:

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

trending(latitude: Optional[float] = None, longitude: Optional[float] = None, near: Optional[str] = None, limit: Optional[int] = None, radius: Optional[int] = 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.