User's Guide

User's Guide and Reference

The Developer's kit includes the User's Guide and Reference pdf. If you want the pdf separately, you can download it here:
Download pdf document

This document describes the OpenStrands web service interface. OpenStrands services allow you to programmatically perform many of the same functions available to you through the MyStrands website using a browser.

Quick Start

OpenStrands web services accept either HTTPS GET or POST requests, with all information encoded in parameter key-value pairs. Every HTTPS request to OpenStrands begins with the base URL:

https://www.MyStrands.com/services/

All requests to OpenStrands require a subscriberId. You must sign up for a subscriber ID before you can use OpenStrands

OpenStrands returns its responses as XML conforming to the schema:

https://www.MyStrands.com/services/namespaces/2006-02-01

You can experiment with OpenStrands requests and responses using nothing more than a Web browser capable of displaying XML documents. Enter an OpenStrands URL into your browser's address bar, and the browser displays the raw XML response.

For example, the request:

https://www.MyStrands.com/services/lookup/artists
?id=15396&id=8625&subscriberId={subscriberId}

where {subscriberId} is your subscriber ID, returns

<?xml version="1.0" encoding="UTF-8"?>
<SimpleArtistList xmlns="https://www.MyStrands.com/services/namespaces/2006-02-01">
    <SimpleArtist Catalog="MusicStrands" ArtistId="15396">
        <ArtistName>Bruce Springsteen</ArtistName>
        <URI>http://www.MyStrands.com/artist/15396</URI>
    </SimpleArtist>
    <SimpleArtist Catalog="MusicStrands" ArtistId="8625">
        <ArtistName>Jimi Hendrix</ArtistName>
        <URI>http://www.MyStrands.com/artist/8625</URI>
    </SimpleArtist>
</SimpleArtistList>

You can call OpenStrands services programmatically from any language capable of issuing a HTTPS request and parsing the XML response. Code examples in Java, C#, and Python are included in the SDK download.

Services

back to top

Account Services

UserValidate

Validates the given username and password.

Parameters: username, password

UserUpdateEmail

Updates a user’s email address (username).

Parameters: username, password, email, emailRepeat
where email and emailRepeat must match exactly

UserUpdatePassword

Changes a user's password.

Parameters: username, password, newPassword, newPasswordRepeat
where newpassword and newPasswordRepeat must match exactly.

UserUpdateShareProfile

Changes a user's profile sharing status.

Parameters: username, password, shareProfile
where shareProfile=true if the profile is to be shared; otherwise, false.

UserUpdateAlias

Changes a user's alias (screen name).

Parameters: username, password, alias

UserLookupProfile

Returns a user’s profile, including location, alias, image URLs, and location information.

Parameters: username, password

Catalog Services

Lookup Services

LookupArtists

Returns metadata for the given artist ids.

Parameters: id(s)

LookupAlbums

Returns metadata for the given album ids.

Parameters: id(s)

LookupTracks

Returns metadata for the given track ids.

Parameters: id(s)

LookupAlbumTracks

Returns a list of the tracks on the given album.

Parameters: id

LookupArtistAlbums

Returns a list of albums in the MyStrands catalog associated with the given artist.

Parameters: id, (num), (skip)where num and skip can be used to page through the results (default num=10, skip=0).

Search Services

SearchArtists

Searches for artists in the MyStrands catalog matching the given search text.

Parameters: searchText, (num), (skip) where num and skip can be used to page through the results (default num=10, skip=0).

SearchAlbums

Searches for albums in the MyStrands catalog matching the given search text.

Parameters: searchText, (num), (skip) where num and skip can be used to page through the results (default num=10, skip=0).

SearchTracks

Searches for tracks in the MyStrands catalog matching the given search text.

Parameters: searchText, (num), (skip) where num and skip can be used to page through the results (default num=10, skip=0).

Browse Services

ListGenres

Returns a list of MyStrands genre names.

Parameters: (num), (skip) where num and skip can be used to page through the results (default num=10, skip=0).

BrowseGenre

Returns a list of albums in the given genre matching the specified browse criteria.

Parameters: genre, searchText, (num), (skip) where genre is a MyStrands genre name, searchText is a letter A-Z or MISC for non-alphabetic items, and num and skip can be used to page through the results (default num=10, skip=0).

BrowseArtists

Returns a list of artists matching the specified browse criteria.

Parameters: searchText, (num), (skip) where searchText is a letter A-Z or MISC for non-alphabetic items, and num and skip can be used to page through the results (default num=10, skip=0).

BrowseAlbums

Returns a list of albums matching the specified browse criteria.

Parameters: searchText, (num), (skip) where searchText is a letter A-Z or MISC for non-alphabetic items, and num and skip can be used to page through the results (default num=10, skip=0).

Recent Items

RecentAlbums

Returns the specified number of most recently released albums in the MyStrands catalog.

Parameters: (num) where the default num=10.

RecentTracks

Returns the specified number of most recently released tracks in the MyStrands catalog.

Parameters: (num) where the default num=10.

Random Items

RandomTracks

Returns the specified number of randomly selected tracks from the MyStrands catalog.

Parameters: (num) where the default num=1.

Resolution Services

MatchArtists

Returns the best matching artists for the given names; or an empty element with ArtistId=-1 if resolution fails.

Parameters: name(s)

MatchAlbums

Returns the best matching albums for the given names; or and empty element with AlbumId=-1 if resolution fails.

Parameters: name(s) where names are a pipe-delimited duple of strings: artist|album

MatchTracks

Returns the best matching tracks for the given names; or an empty element with TrackId=-1 if resolution fails.

Parameters: name(s) where names are a pipe-delimited triple of strings: artist|album|track

Recommendation Services

RecommendArtists

Generates artist recommendations.

Parameters: id(s), name(s), (skip), (num), (filters), (alias) where skip and num can be used to page through the results (default skip=0, num=10).

RecommendAlbums

Generates album recommendations. Any given names are first resolved.

Parameters: id(s), name(s), (skip), (num), (filters), (alias) where names are a pipe-delimited duple of strings: artist|album and skip and num can be used to page through the results (default skip=0, num=10).

RecommendTracks

Generates track recommendations. Any given names are first resolved.

Parameters: id(s), name(s), (skip), (num), (filters), (alias) where names are a pipe-delimited triple of strings: artist|album|track and skip and num can be used to page through the results (default skip=0, num=10)

Playlist Services

General Services

LookupPlaylists

Returns metadata for the given playlists.

Parameters: key(s)

SearchPlaylists

Searches for playlists in the MyStrands catalog matching the given search text.

Parameters: searchText, (num), (skip) where num and skip can be used to page through the results (default num=10, skip=0).

BrowsePlaylists

Returns a list of playlists matching the specified browse criteria.

Parameters: searchText, (num), (skip) where searchText is a letter A-Z or MISC for non-alphabetic items, and num and skip can be used to page through the results (default num=10, skip=0).

TopRatedPlaylists

Returns the top rated playlists.

Parameters: (num), (skip), (lookupTracks), (lookupTags) where num and skip can be used to page through the results (default num=10, skip=0); if lookupTracks=true, metadata for reported track ids is included in the results (default=false); if lookupTags=true, a list of community tags associated with each playlist is returned (default=false).

FeaturedPlaylists

Returns the currently featured playlists on the website.

Parameters: (num), (skip), (lookupTracks), (lookupTags) where num and skip can be used to page through the results (default num=10, skip=0); if lookupTracks=true, metadata for reported track ids is included in the results (default=false); if lookupTags=true, a list of community tags associated with each playlist is returned (default=false).

RecentPlaylists

Returns the most recently added or modified playlists.

Parameters: (num), (skip), (lookupTracks), (lookupTags) where num and skip can be used to page through the results (default num=10, skip=0); if lookupTracks=true, metadata for reported track ids is included in the results (default=false); if lookupTags=true, a list of community tags associated with each playlist is returned (default=false).

Exchange Playlist Services

DownloadPlaylist

Downloads the given playlist.

Parameters: key

DownloadPlaylistTracks

Downloads the given playlist.

Parameters: key

UserUploadPlaylist

Uploads the given playlist

Parameters: username, password, playlist

UserUploadPlaylistTracks

Uploads the given set of tracks as a playlist.

Parameters: username, password, name, id(s) where id is a track id.

Tagging Services

General Services

LookupTags

Returns metadata for the given tags.

Parameters: tag(s)

SearchTags

Searches for tags matching the given search text.

Parameters: searchText, (num), (skip) where num and skip can be used to page through the results (default num=10, skip=0).

BrowseTags

Returns a list of tags matching the specified browse criteria.

Parameters: searchText, (num), (skip) where searchText is a letter A-Z or MISC for non-alphabetic items, and num and skip can be used to page through the results (default num=10, skip=0).

RecommendTags

Generates tag recommendations.

Parameters: tag, (num) where num defaults to 10.

Tag Retrieval Services

LookupTrackTags

Returns a list of all community tags associated with the given track id.

Parameters: id

LookupPlaylistTags

Returns a list of all community tags associated with the given playlist.

Parameters: key

UserLookupTrackTagsTags

Returns a list of the personal tags associated with the given track id.

Parameters: username, password, id

UserLookupPlaylistTags

Returns a list of the personal tags associated with the given playlist.

Parameters: username, password, key

Tag Replacement Services

UserTagTracks

Replaces the personal user tags for the given tracks with the given list of tags.

Parameters: username, password, id(s), (tags) If no tags are given, the personal user tags for the given tracks are cleared.

UserTagPlaylists

Replaces the personal user tags for the given playlists with the given list of tags.

Parameters: username, password, key(s), (tags) If no tags are given, the personal user tags for the given playlists are cleared.

Retrieval By Tag Services

LookupTracksByTag

Returns a list of tracks with the given community tag.

Parameters: tag, (num), (skip) where num and skip can be used to page through the results (default skip=0, num=10)

LookupPlaylistsByTag

Returns a list of playlists with the given community tag.

Parameters: tag, (num), (skip) where num and skip can be used to page through the results (default skip=0, num=10)

Community Services

General Services

SearchUsers

Search users by alias (screen name).

Parameters: searchText, (num), (skip) where num and skip can be used to page through the results (default num=10, skip=0).

BrowseUsers

Browses users by alias (screen name).

Parameters: searchText, (num), (skip) where searchText is a letter A-Z or the word MISC for nonalphabetic aliases, and num and skip can be used to page through the results (default num=10, skip=0).

RecommendUsers

Generates user recommendations for the given user.

Parameters: alias, (num), (lookupUser), (showStatus) where if lookupUsers=true, metadata for users is included in the results (default=false). If showStatus=true, the online status of each returned user is included in the result (default=false).

Play History Services

Online

Returns the online status of the given users.

Parameters: alias(es)

ListeningHistory

Returns the latest tracks played by users, in reverse chronological order.

Parameters: (num), (skip), (unique), (lookupUsers), (lookupTracks), (showPlaying), (showPlayed), (showOrphans), (showStatus) where num and skip can be used to page through the results (default num=10, skip=0); if unique=true, only the most recent play event for a given track is returned (default=true) ; if lookupUsers=true or lookupTracks=true, metadata for reported ids is included in the results (default=false); if showPlaying=true, currently playing events are included (default=true); if showPlayed=true, completed play events are included (default=true); if showOrphans=true, play events for orphan tracks are included (default=true); if showStatus=true, the online status of each returned user is included in the result (default=false).

ListeningHistoryUser

Returns the latest tracks played by the given user, in reverse chronological order.

Parameters: alias, (num), (skip), (unique), (lookupUsers), (lookupTracks), (showPlaying), (showPlayed), (showOrphans), (showStatus) where num and skip can be used to page through the results (default num=10, skip=0); if unique=true, only the most recent play event for a given track is returned (default=true) ; if lookupUsers=true or lookupTracks=true, metadata for reported ids is included in the results (default=false); if showPlaying=true, currently playing events are included (default=true); if showPlayed=true, completed play events are included (default=true); if showOrphans=true, play events for orphan tracks are included (default=true); if showStatus=true, the online status of each returned user is included in the result (default=false).

ListeningHistoryTrack

Returns the latest users to play the given track, in reverse chronological order.

Parameters: id, (num), (skip), (unique) , (lookupUsers), (lookupTracks), (showPlaying), (showPlayed), (showStatus) where num and skip can be used to page through the results (default num=10, skip=0); if unique=true, only the most recent play event for a given user is returned (default=true); if lookupUsers=true or lookupTracks=true, metadata for reported ids is included in the results (default=false); if showPlaying=true, currently playing events are included (default=true); if showPlayed=true, completed play events are included (default=true); if showStatus=true, the online status of each returned user is included in the result (default=false).

Statistical Services

Artist Statistics

TopArtistsDay

Returns the top artists for the given day.

Parameters: date, (num), (skip) where date is specified according to the ISO 8601 standard in the format yyyy-mm-dd, and num and skip can be used to page through the results (default num=10, skip=0).

TopArtistsWeek

Returns the top artists for the week preceding to the given date.

Parameters: date, (num), (skip) where date is specified according to the ISO 8601 standard in the format yyyy-mm-dd, and num and skip can be used to page through the results (default num=10, skip=0).

TopArtistsMonth

Returns the top artists for the month preceding to the given date.

Parameters: date, (num), (skip) where date is specified according to the ISO 8601 standard in the format yyyy-mm-dd, and num and skip can be used to page through the results (default num=10, skip=0).

Track Statistics

TopTracksArtist

Returns the top tracks for a given artist.

Parameters: artistId, (num) where num is the maximum number of results (default=10).

TopTracksDay

Returns the top tracks for the given day.

Parameters: date, (num), (skip) where date is specified according to the ISO 8601 standard in the format yyyy-mm-dd, and num and skip can be used to page through the results (default num=10, skip=0).

TopTracksWeek

Returns the top tracks for the given week.

Parameters: date, (num), (skip) where date is specified according to the ISO 8601 standard in the format yyyy-mm-dd, and num and skip can be used to page through the results (default num=10, skip=0).

TopTracksMonth

Returns the top tracks for the given month.

Parameters: date, (num), (skip) where date is specified according to the ISO 8601 standard in the format yyyy-mm-dd, and num and skip can be used to page through the results (default num=10, skip=0).

Tag Statistics

TopTags

Returns the specified number of top (most popular ever) tags.

Parameters: (num)

HotTags

Returns the specified number of hot (most popular today) tags.

Parameters: (num)

back to top

Contents

powered by OpenStrands