foursquare-swarm-ical

Overview

Sync Foursquare Swarm check-ins to local sqlite DB (incrementally) and generate iCalendar.

Installation

Using uv:

$ uv tool install foursquare-swarm-ical

Using pipx:

$ pipx ensurepath
$ pipx install foursquare-swarm-ical

From a git clone:

$ git clone https://github.com/liskin/foursquare-swarm-ical
$ uv tool install ./foursquare-swarm-ical

Setup and usage

• Obtain a Foursquare API Access Token. The easiest way to obtain one is to use their API Exporer. Grant it permission for your account, open DevTools, let it execute an API call and then inspect the request and copy oauth_token from the Query String Parameters.

  • Chrome: https://developer.chrome.com/docs/devtools/network/reference#payload-encodings
  • Firefox: https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor/request_list

• Run foursquare-swarm-ical:

  $ foursquare-swarm-ical --access-token TOKENTOKENTOKEN --max-size 1M -o swarm-checkins.ical
  

• Import swarm-checkins.ical into your calendar app of choice.

  (Note that Google Calendar refreshes iCal URLs once a day and cannot be tweaked in any way. Manual refresh isn't possible either.)

Command line options

$ foursquare-swarm-ical --help
Usage: foursquare-swarm-ical [OPTIONS]

  Sync Foursquare Swarm check-ins to local sqlite DB and generate iCalendar

Options:
  -v, --verbose             Logging verbosity (0 = WARNING, 1 = INFO, 2 =
                            DEBUG)
  --sync / --no-sync        Sync again or just use local database?  [default:
                            sync]
  --full / --no-full        Perform full sync instead of incremental
                            [default: no-full]
  --access-token TEXT       Foursquare oauth2 access token  [env var:
                            FOURSQUARE_TOKEN]
  --database PATH           SQLite database file  [default: /home/user/.local/
                            share/foursquare_swarm_ical/checkins.sqlite]
  -e, --emoji / --no-emoji  Prefix summary with venue category as emoji
                            [default: emoji]
  -o, --output FILENAME     Output file
  -m, --max-size SIZE       Maximum size of the output file in bytes (accepts
                            K and M suffixes as well)
  --skip-errors BOOLEAN     Skip check-ins on error and log them.  [default:
                            False]
  --config FILE             Read configuration from FILE.  [default: /home/use
                            r/.config/foursquare_swarm_ical/config.yaml]
  --config-sample           Show sample configuration file
  --help                    Show this message and exit.

Configuration file

Access token (and other options) can be set permanently in a config file, which is located at ~/.config/foursquare_swarm_ical/config.yaml by default (on Linux; on other platforms see output of --help).

Sample config file can be generated using the --config-sample flag:

$ foursquare-swarm-ical --config-sample
# Logging verbosity (0 = WARNING, 1 = INFO, 2 = DEBUG)
verbose: 0

# Sync again or just use local database?
sync: true

# Perform full sync instead of incremental
full: false

# Foursquare oauth2 access token
access_token: TEXT

# SQLite database file
database: /home/user/.local/share/foursquare_swarm_ical/checkins.sqlite

# Prefix summary with venue category as emoji
emoji: true

# Output file
output: '-'

# Maximum size of the output file in bytes (accepts K and M suffixes as well)
max_size: SIZE

# Skip check-ins on error and log them.
skip_errors: false

Contributing

Code

We welcome bug fixes, (reasonable) new features, documentation improvements, and more. Submit these as GitHub pull requests. Use GitHub issues to report bugs and discuss non-trivial code improvements; alternatively, get in touch via IRC/Fediverse/email.

See CONTRIBUTING.md for more details about the code base (including running tests locally).

Note that this project was born out of a desire to solve a problem I was facing. While I'm excited to share it with the world, keep in mind that I'll be prioritizing features and bug fixes that align with my personal use cases. There may be times when I'm busy with other commitments and replies to contributions might be delayed, or even occasionally missed. Progress may come in bursts. Adjust your expectations accordingly.

Donations (♥ = €)

If you like this tool and wish to support its development and maintenance, please consider a small donation or recurrent support through GitHub Sponsors.

By donating, you'll also support the development of my other projects. You might like these:

• strava-offline – Keep a local mirror of Strava activities for further analysis/processing
• strava-ical – Generate iCalendar with your Strava activities