Developers » Streaming API Documentation
Streaming API Documentation
1. Authorization
2. Rules Format
3. Methods List
4. Getting Rules
5. Adding Rules
6. Deleting Rules
7. Getting Stream
7.1. Service message
8. Error Messages

 
Note that Streaming API is available in beta testing mode. This documentation could be changes and amended.

Streaming API transfers data via the WebSocket protocol. You create a stream, add necessary rules and receive data matching the rules.
With Streaming API you can receive not more than 1% of all public data matching the rules set. To get access to the extended Streaming API version that includes 100% data please contact us via email: ���api@vk.com��� with �Streaming API� as a subject. Note that this documentation corresponds to the Streaming API basic version and some features of the extended version could be not mentioned.

We made a usage example in Go language. You may find it in our Github repository.
1. Authorization
Use the streaming.getServerUrl API method to get the credentials required to start working. As a result it returns a URL for further requests in the ���endpoint��� (string) field and an access key in the key (string) field.

Authorization example in Go (GitHub).
2. Rules Format
A rule is a set of keywords. If they present in an object text, that object gets into the stream.
  • If the words are listed without double quotes, the search will be simplified (all word forms, case insensitive).
  • To search an exact match (all word forms, case sensitive etc.) each word should be put inside double quotes.
  • Use minus (-) to exclude text with this keyword.

Each rule has a ���value���, the rule�s content and a ���tag���. With each object you receive a list of its tags to figure out what rules does it fit.

Limitations
  • the maximum number of rules � 300;
  • the maximum number of keywords in a rule � 100;
  • the maximum length of a rule (value) in bytes � 4096;
  • the maximum length of a rule's tag (tag) in bytes � 256;
1. Methods List
You need the following methods to work with Streaming API:
In a result all methods return an object in JSON format or HTTP status 503 in case of unexpected error on the server. Each JSON object contains the code (integer) field that defines its contents:
  • code = 100 � object contains an event;
  • code = 200 � determines a successful request execution;
  • code = 300 � object contains a service message;
  • code = 400 � object contains an error message.
4. Getting Rules
Example of adding a rule to a stream in Go (Github).

The method get following rules from a stream.

MethodHTTP GET
URL �������https://{endpoint}/rules?key={key}
key and endpoint parameters are received from streaming.getServerUrl method.

Result
Returns an object with following fields:
  • code (integer) � reply code. Possible values: ��200��, ��400��.
  • rules (array) � (for code = 200) info about rules in the stream. Each object in the ���rules��� array contains following fields:
    • value (string) � string representation of the rule;
    • tag (string) � rule�s tag.
  • error (object) � (for code = 400) error description. An object containing the fields:
    • message (string) � error message;
    • error_code (integer) � error code.

Result Example
{"code":200,"rules":[{"tag":"1","value":"cats"},{"tag":"2","value":"and"}]}
5. Adding Rules
Example of deleting a rule from a stream in Go (Github)

The method adds a new rule to a stream.
MethodHTTP POST
Content Typeapplication/json
URL �������https://{endpoint}/rules?key={key}
key and endpoint parameters are received from streaming.getServerUrl method.

Request Body
In a request body send a JSON object (���rule���) describing a new rule. The ���rule��� object contains following fields:
  • value (string) � string representation of the rule;
  • tag (string) � rule�s tag.

For example:
{"rule":{"value":"vk","tag":"3"}}

Result
Returns an object with fields:
  • code (integer) � reply code. Possible values: ��200��, ��400��.
  • error (object) � (for code = 400) error description. An object containing the fields:
    • message (string) � error message;
    • error_code (integer) � error code.

Result Example
{"code":200}
{"code":400,"error":{"message":"Tag already exist","error_code":2001}}
6. Deleting Rules
Example of deleting a rule from a stream in Go (GitHub).

The method removes a rule from a stream.
MethodHTTP DELETE
Content Typeapplication/json
URL �������https://{endpoint}/rules?key={key}
key and endpoint parameters are received from streaming.getServerUrl method.

Request Body
In a request body send the tag (string) field containing a tag of the rule you need to remove.

For example:
{"tag":"1"}


Result
Returns an object with fields:
  • code (integer) � reply code. Possible values: ��200��, ��400��.
  • error (object) � (for code = 400) error description. An object containing the fields:
    • message (string) � error message;
    • error_code (integer) � error code.

Result Example
{"code":200}
{"code":400,"error":{"message":"Tag not exist","error_code":2002}}


More...


By continuing to browse, you consent to our use of cookies. You can read our Cookie Policy here.