Metadata-Version: 2.4
Name: foursquare-swarm-ical
Version: 1.1.0
Summary: Sync Foursquare Swarm check-ins to local sqlite DB and generate iCalendar
Author-email: Tomáš Janoušek <tomi@nomi.cz>
License-Expression: MIT
Project-URL: Homepage, https://github.com/liskin/foursquare-swarm-ical
Project-URL: Release Notes, https://github.com/liskin/foursquare-swarm-ical/releases
Project-URL: Issues, https://github.com/liskin/foursquare-swarm-ical/issues
Project-URL: CI, https://github.com/liskin/foursquare-swarm-ical/actions
Project-URL: Donations (GitHub), https://github.com/sponsors/liskin
Project-URL: Donations (PayPal), https://www.paypal.me/lisknisi/5EUR
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=5.1
Requires-Dist: click>=8.1.1
Requires-Dist: click-config-file>=0.6.0
Requires-Dist: foursquare==1!2020.1.30
Requires-Dist: icalendar>=5.0.2
Requires-Dist: platformdirs>=2.1
Dynamic: license-file

# foursquare-swarm-ical

[![PyPI Python Version badge](https://img.shields.io/pypi/pyversions/foursquare-swarm-ical)](https://pypi.org/project/foursquare-swarm-ical/)
[![PyPI Version badge](https://img.shields.io/pypi/v/foursquare-swarm-ical)](https://pypi.org/project/foursquare-swarm-ical/)
![License badge](https://img.shields.io/github/license/liskin/foursquare-swarm-ical)

## Overview

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

![Example screenshot of the output in Google Calendar](https://github.com/liskin/foursquare-swarm-ical/assets/300342/b2c88749-3196-4645-8e2d-8574e19dfaa5)

## Installation

Using [uv][]:

```console
$ uv tool install foursquare-swarm-ical
```

Using [pipx][]:

```console
$ pipx ensurepath
$ pipx install foursquare-swarm-ical
```

From a git clone:

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

[uv]: https://docs.astral.sh/uv/
[pipx]: https://github.com/pypa/pipx

## Setup and usage

* Obtain a Foursquare API Access Token. The easiest way to obtain one is to
  use their [API Exporer](https://foursquare.com/developers/explore/). 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

<!-- include tests/readme/help.md -->
<!--
    $ . "$TESTDIR"/../.xdg-user.sh
-->

    $ 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.
<!-- end include tests/readme/help.md -->

## 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:

<!-- include tests/readme/config-sample.md -->
<!--
    $ . "$TESTDIR"/../.xdg-user.sh
-->

    $ 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
<!-- end include tests/readme/config-sample.md -->

## 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](https://work.lisk.in/contact/).

See [CONTRIBUTING.md](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](https://www.paypal.me/lisknisi/5EUR) or
[recurrent support through GitHub Sponsors](https://github.com/sponsors/liskin).

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

* [strava-offline](https://github.com/liskin/strava-offline) – Keep a local mirror of Strava activities for further analysis/processing
* [strava-ical](https://github.com/liskin/strava-ical) – Generate iCalendar with your Strava activities
