VKHS: Provides access to Vkontakte social network via public API

[ bsd3, library, program, web ] [ Propose Tags ]

Provides access to Vkontakte API methods. Library requires no interaction with the user during Implicit-flow authentication.

[Skip to Readme]
Versions [faq] 0.0.1, 0.0.2, 0.0.3, 0.1.0, 0.1.1, 0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.1.6, 0.2.0, 0.3.0, 0.3.1, 0.3.2, 0.3.3, 0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4, 0.5.5, 0.5.6, 0.5.7, 1.6.0, 1.6.1, 1.6.2, 1.6.3, 1.6.4, 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.9, 1.9.1, 1.9.2
Change log CHANGELOG.md
Dependencies aeson, aeson-pretty, base (>=4.6 && <5), bytestring, case-insensitive, clock, containers, data-default-class, directory, filepath, http-client, http-client-tls, http-types, mtl, network-uri, optparse-applicative, parsec, pipes, pipes-http, pretty-show, regexpr, scientific, split, tagsoup, text, time, utf8-string, vector [details]
License BSD-3-Clause
Copyright Copyright (c) 2012, Sergey Mironov
Author Sergey Mironov
Maintainer grrwlf@gmail.com
Category Web
Home page http://github.com/grwlf/vkhs
Uploaded by SergeyMironov at 2017-06-28T21:11:21Z
Distributions NixOS:1.9.2
Executables vkq
Downloads 27246 total (90 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2017-06-28 [all 1 reports]




Maintainer's Corner

For package maintainers and hackage trustees

Readme for VKHS-1.8.3

[back to package description]


VKHS provides access to Vkontakte social network, popular mainly in Russia. Library can be used to login into the network as a standalone application (OAuth implicit flow as they call it). Having the access token, it is possible to call various API methods to query audio files or retrieve wall messages. For now, vkhs offers limited error detection and no captcha support.


  • Provide access to VK API. Interface options include: VK monad and vkq command line tool.
  • Use HTTPS protocol.
  • Solve login form interaction, may be used to operate new/disposable VK accounts.
  • VK monad is an interruptable coroutine. The superwiser supports ondemand re-login, and may be used for long-running tasks.
  • Project includes a set of Web.VKHS.API.Simple wrappers designed to be copied into runhaskell scripts and tweaked according to ones need.


  • Still no support for captchas, one probably should hack defaultSuperwiser and add them
  • Network connection timeout is not handled by superwiser
  • Minor issues here and there. Use git grep FIXME to find them
  • File uploading still not functioning


Installing from Hackage

In order to install VKHS, one typically should do the following

$ cabal update
$ cabal install VKHS

Note, that VKHS uses curlhs and should be linked with libcurl.so. Normally, cabal handles it without problems.

Installing from source

$ git clone https://github.com/grwlf/vkhs
$ cd vkhs
$ cabal install

Developing using Nix

The author of this project uses Nix as a main development platform. Typical development procedure includes the following steps:

$ git clone https://github.com/grwlf/vkhs
$ cd vkhs
$ nix-shell

  .. Entering Nix shell environment

$ ghci -isrc:app/vkq:app/common
$ exit

  ..  Now exiting from the Nix shell

$ nix-build

The default.nix file contain Nix expression describing the environment

Building ctags file

./mktags.sh script may be used to build ctags file. It used haskdogs tool, which should be installed from Hackage.

$ haskdogs

VKQ command line application

vkq is a command line tool which demonstrates API usage. It can be used for logging in, downloading music and reading wall messages. Call vkq --help or vkq --help [command] to read online help.

Log in to VK

Here is an example session: Login first

$ vkq login user@mail.org pass123

VKQ returns three values. First one is an access token required to execute all API requests. vkq tries to reads it from VKQ_ACCESS_TOKEN environment variable or from .vkhs-access-token file (may be changed using options).

$ export VKQ_ACCESS_TOKEN=d785932b871f096bd73aac6a35d7a7c469dd788d796463a871e5beb5c61bc6c96788ec2

VKQ may cache the access tokein into a state file:

$ vkq login --access-token-file=.access-token

.. VKQ will ask for email/password and cache the access token

$ vkq call groups.search q=Beatles --pretty --access-token-file=.access-token

Latest versions of the library have --access-token-flag option enabled by default. Set it to empty value to disable the caching feature.

Performing custom API calls

vkq allows user to call arbitrary API method. The format is as follows:

Usage: vkq call [--verbose] [--req-per-sec N] [--interactive] [--appid APPID]
                [--user USER] [--pass PASS] [-a ACCESS_TOKEN] METHOD PARAMS

For example, lets call ausio.search method to get some Beatles records:

$ vkq call group.search q=Beatles --pretty

  { "response": [
        "lyrics_id": "6604412",
        "url": "http://cs1-36v4.vk-cdn.net/p16/59674dd8717db2.mp3?extra=k0s2ja3l6pq6aIDOEW5y5XUCs2--JLX9wZpzOT3iuSnZPR-DNhJSF075NUhICB_szMOKKlVJFFlqLlg691q6cKhwiGZgTRU1oAimXzXY396cfNAHnotc8--7w-0xnvoPK6qVoI8",
        "aid": 85031440,
        "title": "Twist and Shout  ",
        "genre": 1,
        "owner_id": 9559206,
        "duration": 156,
        "artist": "The Beatles"

VKHS library/runhaskell mode

Starting from 1.7.2 the library supports RunHaskell-mode. Consider the following example:

#!/usr/bin/env runhaskell
{-# LANGUAGE RecordWildCards #-}

import Prelude ()
import Web.VKHS
import Web.VKHS.Imports

main :: IO ()
main = runVK_ defaultOptions $ do
  Sized cnt cs <- getCountries
  forM_ cs $ \Country{..} -> do
    liftIO $ putStrLn co_title

When executed, the program asks for login/password and outputs list of countries known to VK. getCountries and several other methods are defined in Web.VKHS.API.Simple. vkq application may be used as a more elaborated example.


Verbosity may be increased using --verbose flag or o_verbose field of GenericOptions. Login automata saves latest.html file during operation.



BSD3 license

Copyright (c) 2014, Sergey Mironov grrwlf@gmail.com