summaryrefslogtreecommitdiff
path: root/json/index.rst
blob: 1a7f576d8c3049b8930421da6038a73c6f31d150 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
JSON API v5
===========


.. index::
   single: API Endpoints

The current JSON API version is 5. Two different endpoints are available:

- http://tuner.pandora.com/services/json/
- https://tuner.pandora.com/services/json/

- http://internal-tuner.pandora.com/services/json/
- https://internal-tuner.pandora.com/services/json/


.. index::
   Blowfish encryption, HTTP request

.. _bodyenc:

Unless noted otherwise JSON-encoded requests sent by the client within the HTTP
POST body are encrypted using Blowfish ECB and converted to hexadecimal
notation with lowercase letters.

These URL parameters must be appended to the endpoint above if available:

==========  ===========
Name        Description
==========  ===========
method      Method name
auth_token  User auth token if available, partner auth token or empty if neither is known yet.
partner_id  Partner id obtained by :ref:`auth-partnerLogin` or empty
user_id     User id as obtained by :ref:`auth-userLogin` or empty
==========  ===========

For instance when calling :ref:`auth-userLogin` two parameters are known:
method and partner_id. The URL in this case would be
``http://tuner.pandora.com/services/json/?method=auth.userLogin&partner_id=123``.
Make sure you URL encode the parameter’s values.

The following values must be present in every JSON request object (if available): 


.. index::
   Time synchronization

.. _synctime:

=============  ======  ===========
Name           Type    Description
=============  ======  ===========
userAuthToken  string  User auth token, see :ref:`auth-userLogin`
syncTime       int     Synchonized time. Calculation: current time + (time of :ref:`auth-partnerLogin` request – syncTime from :ref:`auth-partnerLogin` response). This is a protection against replay-attacks.
=============  ======  ===========

Every response includes the key ``stat`` which indicates success (``ok``) or
failure (``fail``) of the resquest. Failed requests contain an error code and
message whereas successful requests carry actual response data in the key
``result``:

.. code:: json

    {
        "stat": "ok",
        "result": {
        }
    }

.. code:: json

    {
        "stat": "fail",
        "message": "An unexpected error occurred",
        "code": 1008
    }

.. toctree::

   authentication
   stations
   play
   bookmarks
   account
   ads
   methods
   errorcodes

.. toctree::
   :hidden:

   partners