API: Users

In this page

The User object

A user has several properties. Each API can return a User model in its entirety or with just a subset. All the properties are listed here:

Property Type Description
user_id Numeric Unique user identifier
fullname String A user’s full name
site_url String Public URL of the user on Spreaker’s website
image_original_url String Original size image URL
image_url String 200x200px size image URL
username String User username
description String User biography
kind String It could be listener or producer
plan String It will be basic for a free account, or other values for a Pro account
followers_count Numeric The number of users following this user
followings_count Numeric The number of users that this user follows
contact_email String Contact email
is_following_you Boolean true if this user follows the requesting user, false otherwise
you_are_following Boolean true if the requesting user follows this user, false otherwise
verified Boolean true if this user has confirmed their email address or social connection, false otherwise
birthday String User birthday
gender String It could be male or female
timezone String The timezone that should be used to convert UTC timestamps, before it is displayed. The timezone value is auto-detected

Many of the resources on the user APIs are related to a single user. If a request URL includes USER-ID it could be the numeric user_id or username.

Retrieving a Single User

GET /v2/users/USER-ID

You can retrieve the public information of a user profile by sending a GET request to the URL above. This API will only return public user profile data, even if the request is authenticated with the requested USER-ID token. To retrieve the full user profile, including private data, you should use the API GET /v2/me.

Example

curl https://api.spreaker.com/v2/users/1

The response body is a JSON object containing all the public user profile fields.

{
  "response": {
    "user": {
      "user_id": 1,
      "fullname": "Marco Pracucci",
      "site_url": "https://www.spreaker.com/user/marco",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/a9c98be54e22d5bad6a951e1c4d04ade.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/a9c98be54e22d5bad6a951e1c4d04ade.jpg",
      "username": "marco",
      "description": "Programming is a wonderful mix of art and science; source code is both a poem and a math problem.",
      "kind": "producer",
      "plan": "station",
      "followers_count": 443,
      "followings_count": 445,
      "contact_email": "info@spreaker.com"
    }
  }
}

Retrieving the Authenticated User

GET /v2/me

Authenticated: yes

You can retrieve all of a user’s profile data, including private information, by sending an authenticated GET request to this API. It can only be used to retrieve the data of an authenticated user.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/me

Updating a User

POST /v2/users/USER-ID

Authenticated: yes. Owner: yes

The API POST /v2/users/USER-ID supports these parameters, none of which are required, as you should specify only the ones you want to update:

Parameter Type Requirements
fullname String Max length: 30
description String -
gender String Allowed: MALE or FEMALE
birthday String A date string with the format YYYY-MM-DD
show_age Boolean -
location String -
location_latitude Numeric -
location_longitude Numeric -
content_languages String ISO 639-1 language code. Allowed: sq ar be bg cs zh hr da et fi fr ja el is lt it en mk no nl pl pt ro ru sr sk sl es sv de tr uk hu
username String Min length: 4. Max length: 30. Can only contain letters, numbers 0-9 and _-.. Must be unique. Can be changed only once
contact_email String -
image_file File At least 400x400, Max size: 5MB, Formats: JPG, PNG
image_crop String Comma-separated coordinates (top left X, top left Y, bottom right X, bottom right Y) are used to crop the image_file. If not specified, the image_file will not be cropped. This parameter is effective only if the request contains an image_file.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "image_file=@image.jpg" -F "fullname=John Smith" -F "description=My biography" -F "gender=MALE" -F "birthday=1975-03-15" -F "show_age=true" -F "location=Chicago, Illinois, United States" -F "location_latitude=41.878114" -F "location_longitude=-87.629798" -F "content_languages=en" -F "username=johnsmith" -F "contact_email=john@smith.com" https://api.spreaker.com/v2/users/12345678

The response body is a JSON object containing all the user fields.

Retrieving a User’s Followers

GET /v2/users/USER-ID/followers

The response body is a paginated list of Users.

{
  "response": {
    "items": [
      {
        "user_id": 8454510,
        "fullname": "TSABS RADIO",
        "site_url": "https://www.spreaker.com/user/tsabs",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/0eb3eaca0e43a65ade6f85598b4ba436.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/0eb3eaca0e43a65ade6f85598b4ba436.jpg"
      },
      {
        "user_id": 7948419,
        "fullname": "Samuel Ceron",
        "site_url": "https://www.spreaker.com/user/sceron1",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/6682202d8ce598ce0b390b9dc1fd3c4d.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/6682202d8ce598ce0b390b9dc1fd3c4d.jpg"
      },
      {
        "user_id": 8631203,
        "fullname": "Tyler Barczewski",
        "site_url": "https://www.spreaker.com/user/8631203",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/4c10de9743694d01f0c99820e288f19a.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/4c10de9743694d01f0c99820e288f19a.jpg"
      }
    ],
    "next_url": null
  }
}

Retrieving Who a User Follows

GET /v2/users/USER-ID/followings

The response body is a paginated list of Users.

{
  "response": {
    "items": [
      {
        "user_id": 4436325,
        "fullname": "GODDAMN RADIO",
        "site_url": "https://www.spreaker.com/user/countessofbrightonandhackney",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/ec68ec0fcd456329eb1149866bb342f8.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/ec68ec0fcd456329eb1149866bb342f8.jpg"
      },
      {
        "user_id": 4379396,
        "fullname": "MundoNet Radio New York",
        "site_url": "https://www.spreaker.com/user/djcharliep",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/8feb62251774ecc231301c2c68e51c7b.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/8feb62251774ecc231301c2c68e51c7b.jpg"
      },
      {
        "user_id": 8619152,
        "fullname": "Julian Clark",
        "site_url": "https://www.spreaker.com/user/afterdarkjulianclark",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/4baf2e39e0bb8346ea96310421101b56.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/4baf2e39e0bb8346ea96310421101b56.jpg"
      },
      {
        "user_id": 8601240,
        "fullname": "Cheyenne Harris Derulo",
        "site_url": "https://www.spreaker.com/user/8601240",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/0b704f0e4c82f35e3db599840f5867d7.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/0b704f0e4c82f35e3db599840f5867d7.jpg"
      }
    ],
    "next_url": null
  }
}

Following a User

PUT /v2/users/USER-ID/followings/FOLLOWED-ID

Authenticated: yes

The USER-ID user follows FOLLOWED-ID. It requires the request to be authenticated with USER-ID credentials.

Unfollowing a User

DELETE /v2/users/USER-ID/followings/FOLLOWED-ID

Authenticated: yes

The USER-ID user unfollows FOLLOWED-ID. It requires the request to be authenticated with USER-ID credentials.

Retrieving a User’s Blocked Users List

Retrieve the list of users blocked by USER-ID

GET /v2/users/USER-ID/blocks

Authenticated: yes

The response body is a paginated list of Users.

{
  "response": {
    "items": [
      {
        "user_id": 4436325,
        "fullname": "GODDAMN RADIO",
        "site_url": "https://www.spreaker.com/user/countessofbrightonandhackney",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/ec68ec0fcd456329eb1149866bb342f8.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/ec68ec0fcd456329eb1149866bb342f8.jpg"
      },
      {
        "user_id": 4379396,
        "fullname": "MundoNet Radio New York",
        "site_url": "https://www.spreaker.com/user/djcharliep",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/8feb62251774ecc231301c2c68e51c7b.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/8feb62251774ecc231301c2c68e51c7b.jpg"
      },
      {
        "user_id": 8619152,
        "fullname": "Julian Clark",
        "site_url": "https://www.spreaker.com/user/afterdarkjulianclark",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/4baf2e39e0bb8346ea96310421101b56.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/4baf2e39e0bb8346ea96310421101b56.jpg"
      },
      {
        "user_id": 8601240,
        "fullname": "Cheyenne Harris Derulo",
        "site_url": "https://www.spreaker.com/user/8601240",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/0b704f0e4c82f35e3db599840f5867d7.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/0b704f0e4c82f35e3db599840f5867d7.jpg"
      }
    ],
    "next_url": null
  }
}

Blocking a User

PUT /v2/users/USER-ID/blocks/BLOCKED-ID

Authenticated: yes

The USER-ID user will add a BLOCKED-ID user in his own Blocked list. It requires the request to be authenticated with USER-ID credentials.

Unblocking a User

DELETE /v2/users/USER-ID/blocks/BLOCKED-ID

Authenticated: yes

The USER-ID user will remove a BLOCKED-ID user from his own Blocked list. It requires the request to be authenticated with USER-ID credentials.