VK scripts
==========

A collection of scripts abusing VK.com API.
Requires Python 3.4 or higher.

Usage
-----

Pass the `--help` flag to a script to see its detailed usage information.

### track_status.py

Track when people go online/offline.

    usage: track_status.py [-h] [-t TIMEOUT] [-l LOG]
                           [--output-format {csv,log,null}] [-o OUTPUT]
                           UID [UID ...]

For example (using made up user IDs/"screen names"),

    > track_status.py john.doe jane.smith
    [2016-06-18 01:43:34] John Doe is ONLINE.
    [2016-06-18 01:43:34] John Doe was last seen at 2016-06-18 01:33:58+03:00 using the official iPhone app.
    [2016-06-18 01:43:34] Jane Smith is OFFLINE.
    [2016-06-18 01:43:34] Jane Smith was last seen at 2016-06-18 01:15:47+03:00 using the web version (or an unrecognized app).
    [2016-06-18 01:59:09] Jane Smith went ONLINE.
    [2016-06-18 01:59:09] Jane Smith was last seen at 2016-06-18 01:59:07+03:00 using the official Android app.
    [2016-06-18 02:10:00] John Doe went OFFLINE.
    [2016-06-18 02:10:00] John Doe was last seen at 2016-06-18 01:54:58+03:00 using the official iPhone app.
    ...

By default, the script produces a human-readable log.
Use the `--log` parameter to write the log to a file.
If you want to record when people go online/offline for [further analysis],
specify the path to a database using the `--output` parameter.
Be careful: if the file already exists, it will be overwritten!

[further analysis]: #online_durationpy

### online_duration.py

View the amount of time people spent online.

    usage: online_duration.py [-h] [--grouping {user,date,weekday}]
                              [--input-format {csv,log,null}]
                              [--output-format {csv,json,img}]
                              input [output]

This script additionally requires [matplotlib] to be installed.

Analyze the database produced by [track_status.py] and calculate the total
amount of time people spent online.

For example (assuming the database in "db.csv" was generated by
[track_status.py] before):

    > online_duration.py db.csv
    89497105,John,Smith,john.smith,0:12:31
    3698577,Jane,Smith,jane.smith,1:34:46

In the example above, "John Smith" and "Jane Smith" spent approx. 13 and 95
minutes online respectively.

The output format is CSV (comma-separated values) by default.
You can also get a JSON document:

    > online_duration.py --output-format json db.csv
    [
       {
          "uid": 89497105,
          "first_name": "John",
          "last_name": "Smith",
          "screen_name": "john.smith",
          "duration": "0:12:31"
       },
       {
          "uid": 3698577,
          "first_name": "Jane",
          "last_name": "Smith",
          "screen_name": "jane.smith",
          "duration": "1:34:46"
       }
    ]

The durations are calculated on a per-user basis by default.
You can change that by supplying either `date` (to group by dates) or `weekday`
(to group by weekdays) as the `--grouping` parameter value.
For example (assuming that both Jane and Joe spent their time online on Friday,
June 17, 2016).

    > online_duration.py --output-format json --grouping date db.csv
    [
       {
          "date": "2016-06-17",
          "duration": "1:47:17"
       }
    ]

    > online_duration.py --output-format csv --grouping weekday db.csv
    Monday,0:00:00
    Tuesday,0:00:00
    Wednesday,0:00:00
    Thursday,0:00:00
    Friday,1:47:17
    Saturday,0:00:00
    Sunday,0:00:00

In my opinion, the script's most useful feature is the ability to easily create
plots that represent the text data (like in the examples above).
To produce a plot, pass `img` as the `--output-format` parameter value and add
a file path to write the image to.

    > online_duration.py --output-format img db.csv user.png

![user.png]

    > online_duration.py --output-format img --grouping date db.csv date.png

![date.png]

    > online_duration.py --output-format img --grouping weekday db.csv weekday.png

![weekday.png]

[matplotlib]: http://matplotlib.org/
[track_status.py]: #track_statuspy

[user.png]: img/online_duration/user.png
[date.png]: img/online_duration/date.png
[weekday.png]: img/online_duration/weekday.png

### mutual_friends.py

Learn who your ex and her new boyfriend are both friends with.

    usage: mutual_friends.py [-h] [--output-format {csv,json}] UID [UID ...]

For example (using made up user IDs/"screen names"),

    > mutual_friends.py john.doe jane.doe
    89497105,John,Smith,john.smith
    3698577,Jane,Smith,jane.smith

In the example above, both "John Doe" and "Jane Doe" are friends with "John
Smith" and "Jane Smith", whose user IDs are 89497105 and 3698577 respectively.
Their "screen names" (the part after "vk.com/" of their personal page URLs) are
"john.smith" and "jane.smith".

The output format is CSV (comma-separated values) by default.
You can also get a JSON document:

    > mutual_friends.py --output-format json john.doe jane.doe
    [
       {
          "uid": 89497105,
          "first_name": "John",
          "last_name": "Smith",
          "screen_name": "john.smith"
       },
       {
          "uid": 3698577,
          "first_name": "Jane",
          "last_name": "Smith",
          "screen_name": "jane.smith"
       }
    ]

License
-------

This project, including all of the files and their contents, is licensed under
the terms of the MIT License.
See [LICENSE.txt] for details.

[LICENSE.txt]: LICENSE.txt