Miso API Endpoints

The Miso APIv1 gives you access to all of the data used by the Miso mobile applications, and, in some cases, even more.

Users

Retrieve user details

GET http://gomiso.com/api/oauth/v1/users/show.json

Retrieves relevant information from a user's profile. If no user is specified, returns the details of the authenticated user.

Parameters

All parameters are optional, unless otherwise indicated.

user_id The user id for the info you would like to retrieve.
If not specified, defaults to authenticated user. 		1234
Response

These are the items you can expect in the api response.
User object contains the additional currently_followed attribute indicating if the user has already been followed.

user The matching User object (fields detailed below).
Error Conditions

These are the errors that are possible from this endpoint.

user_id 404 The user cannot be found.

Search for users

GET http://gomiso.com/api/oauth/v1/users.json

Searches for users with a first name, last name, username or email that matches the given query string

Parameters

All parameters are optional, unless otherwise indicated.

q (Required) The search query string. If this parameter is formatted like an email address, users with matching emails will be returned, otherwise matches will be found on the user's first name, last name and username 1234
count The number of results you'd like returned. The default is 15 if no value is passed, otherwise you may select a value between 1 and 50. 1234
Response

These are the items you can expect in the api response.
All users contain the additional currently_followed attribute indicating if the user has already been followed.

users An array of matching basic User objects (fields detailed below).
Error Conditions

These are the errors that are possible from this endpoint.

q 400 Search query cannot be blank

Retrieve user's followers

GET http://gomiso.com/api/oauth/v1/users/followers.json

Retrieves all users that follow a specified account. If no user is specified, returns the followers of the authenticated user.

Parameters

All parameters are optional, unless otherwise indicated.

user_id The user id for the info you would like to retrieve.
If not specified, defaults to authenticated user. 		1234
Response

These are the items you can expect in the api response.

Array A list of basic User objects (fields explained below).
Error Conditions

These are the errors that are possible from this endpoint.

user_id 404 The user cannot be found.

Retrieve followed users

GET http://gomiso.com/api/oauth/v1/users/follows.json

Retrieves all users that a specified account follows. If no user is specified, returns the follows of the authenticated user.

Parameters

All parameters are optional, unless otherwise indicated.

user_id The user id for the info you would like to retrieve.
If not specified, defaults to authenticated user. 		1234
Response

These are the items you can expect in the api response.

Array A list of basic User objects (fields explained below).
Error Conditions

These are the errors that are possible from this endpoint.

user_id 404 The user cannot be found.

Follow new user

POST http://gomiso.com/api/oauth/v1/users/follows.json

Account creates a following relationship with specified user by id.

Parameters

All parameters are optional, unless otherwise indicated.

user_id (Required) The user id for the user that should be followed. 1234
Response

These are the items you can expect in the api response.

Code A 201 response code ("created") if the follow was successful.
Error Conditions

These are the errors that are possible from this endpoint.

user_id 404 The user cannot be followed.
Error Keys

These are the error keys that are possible from this endpoint.

following_id_taken The user has already been followed.
following_id_not_found The user cannot be found.

Unfollow user

DELETE http://gomiso.com/api/oauth/v1/users/follows.json

Account removes a follow relationship with specified user by id.

Parameters

All parameters are optional, unless otherwise indicated.

user_id (Required) The user id for the user that should no longer be followed. 1234
Response

These are the items you can expect in the api response.

Code A 200 response code ("success") if the unfollow was successful.
Error Conditions

These are the errors that are possible from this endpoint.

user_id 404 The user cannot be unfollowed.

Object Representation

A User object is represented with the basic following fields:

id The user id for this user. 1234
username The user's username. john24
profile_image_url The url to the user's profile image. http://gomiso.com/uploads/BAhbCFsHOgZm.png
full_name The user first and last name (if available). John Smith
tagline The user's chosen profile tagline. TV is Great

Extended details for users are:

currently_followed Only returned for user search and user show actions. Will return "true" if the currently logged in user is following given user and "false" if (s)he is not. true
total_points The total points the user has earned. 10
badge_count The number of badges the user has earned. 4
checkin_count The number of times the user has checked in. 22
following_count The number of users this user is following. 5
follower_count The number of followers this user has. 67
twitter Exists only if user has a linked Twitter account. (Node)
twitter.id The twitter account's unique id. 56789
twitter.share_checkins Returns true if the user wants checkins posted to Twitter by default. false
facebook Exists only if user has a linked Facebook account. (Node)
facebook.id The facebook account's unique id. 76854
facebook.share_checkins Returns true if the user wants checkins posted to Facebook by default. true

Media

Search our media listings

GET http://gomiso.com/api/oauth/v1/media.json

Retrieves media listing information based on a given query.

Parameters

All parameters are optional, unless otherwise indicated.

q (Required) Partial title for a given media. Dark
kind Filter for the type of Media. 'TvShow' or 'Movie'
count The total matching items to return (1-50). 25
Response

These are the items you can expect in the api response.

Array A list of basic Media objects (fields explained below).

Retrieve media details

GET http://gomiso.com/api/oauth/v1/media/show.json

Retrieves relevant information about specified media.

Parameters

All parameters are optional, unless otherwise indicated.

media_id (Required) The media id for the info you would like to retrieve. 1234
Response

These are the items you can expect in the api response.

media The extended Media object (fields detailed below).
Error Conditions

These are the errors that are possible from this endpoint.

media_id 404 The media cannot be found.

Retrieve trending media

GET http://gomiso.com/api/oauth/v1/media/trending.json

Retrieves a list of currently trending media. Trending refers to media with the most recent checkins.

Parameters

All parameters are optional, unless otherwise indicated.

count The total matching items to return (1-100). 25
Response

These are the items you can expect in the api response. All media contain the additional watching_count attribute representing the number of recent checkins.

Array A list of basic Media objects (fields detailed below).

Retrieve favorited media

GET http://gomiso.com/api/oauth/v1/media/favorites.json

Retrieves a list of favorited media by user. Favorited refers to media that the user has marked as favorites.

Parameters

All parameters are optional, unless otherwise indicated.

user_id The user id for the info you would like to retrieve.
If not specified, defaults to authenticated user. 		1234
Response

These are the items you can expect in the api response.

Array A list of basic Media objects (fields detailed below).
Error Conditions

These are the errors that are possible from this endpoint.

user_id 404 The user cannot be found.

Mark new favorite media

POST http://gomiso.com/api/oauth/v1/media/favorites.json

Marks a new favorite media for authenticated user.

Parameters

All parameters are optional, unless otherwise indicated.

media_id (Required) The media id for the info you would like to favorite. 1234
Response

These are the items you can expect in the api response.

Code A 201 response code ("created") if the favorite was successful.
Error Conditions

These are the errors that are possible from this endpoint.

media_id 404 The entity is not found
media_id 400 Cannot complete operation

Unmark favorite media

DELETE http://gomiso.com/api/oauth/v1/media/favorites.json

Unmarks a favorited media for authenticated user.

Parameters

All parameters are optional, unless otherwise indicated.

media_id (Required) The media id for the info you would like to unfavorite. 1234
Response

These are the items you can expect in the api response.

Code A 200 response code ("success") if the unfavorite was successful.
Error Conditions

These are the errors that are possible from this endpoint.

media_id 404 The entity is not found
media_id 400 Cannot complete operation

Object Representation

A Media object is represented with the basic following fields:

id The id for this media object. 5678
title The media title for this object. The Dark Knight
poster_image_url The poster image for this media object. http://gomiso.com/uploads/BAhbCFsHOgZm.png
poster_image_url_small The thumbnail poster image for this media object. http://gomiso.com/uploads/BAhbCFsHOgZm.png
kind The media object's type. 'TvShow' or 'Movie'
release_year The year the movie was released or the show started. 2011
tvdb_id The tvdb id associated with this media, if available. tt1234
currently_favorited The media is currently favorited by the logged in user. true
episode_count The total number of episodes aired for this media (if it's a TV Show) 123
latest_episode An episode object representing the most recently aired episode for this media (if it's a TV Show) See Episode Representation

Extended details for media are:

genres Comma-delimited genres related to this media. Drama, Mystery
cast Comma-delimited actors related to this media. Christian Bale, Heath Ledger
summary The summary of the storyline for this media. Batman faces the Joker in an epic battle.
viewing_count The total number of checkins to this media. 1000
followers_count The total number of users following this media. 800

Feeds

Retrieve user and media feeds

GET http://gomiso.com/api/oauth/v1/feeds.json

Retrieves feed for a given user or media. A feed includes items of various types, such as checkins, badges, links, notes, ratings. Properties of feed items vary depending on the type, documented in Object Representation below.

Parameters

All parameters are optional, unless otherwise indicated.

user_id Retrieves all feed items for the given user. 1234
media_id Retrieves all feed items for the given media. 5678
max_id Retrieves all feed items before a given feed item id. 7891
since_id Retrieves all feed items after a given feed item id. 3456
count The total matching items to return (1-50). 25
Response

These are the body you can expect in the api response.

Array A list of Feed item objects (fields detailed below).

Retrieve home feed

GET http://gomiso.com/api/oauth/v1/feeds/home.json

Retrieves home feed of the authenticated user, i.e., all the checkins and badges of users that the authenticated user follows.

Parameters

Same parameters as above.

Object Representation

A Feed item object is represented with the following fields:

id The id for this feed item object. 9876
type The type for this feed item object. checkin, rating
user The user that created this feed item. { user_id: 123, full_name: "John Smith", profile_image_url: "http://gomiso.com/uploads/BAhbCFsHOgZm.png" }
created_at The timestamp for when this feed item was created "2010-12-11T00:21:44Z"
body The comment associated with the feed item. checkins, notes, and ratings may have a comment. Dexter is a great show
topics A dictionary of associated topics, may contain a media, episode, badge object. { media: {...}, episode: {...}, badge: {...}}
rating The rating associated with the feed item. Only ratings will have a rating. Dexter is a great show
url The URL associated with the feed item. Only links will have a URL. http://www.dexter.com
image_url The image URL associated with the feed item. Only links will have an image URL. http://www.dexter.com
likes_count The number of users who have "liked" the feed item. 1
likes An array of users who have "liked" the feed item. [ "like" : { user_id : 123, full_name : "John Smith", profile_image_url: "http://gomiso.com/uploads/BAhbCFsHOgZm.png" } ]
comments_count The number of users who have commented on the feed item. 1
comments An array of users who have commented on the feed item. [ "comment" : { user_id : 123, full_name : "John Smith", profile_image_url: "http://gomiso.com/uploads/BAhbCFsHOgZm.png", body : "What is that show about?" } ]

Checkins

Retrieve recent checkins

GET http://gomiso.com/api/oauth/v1/checkins.json

Retrieves recent checkin information for a given user or media.

Parameters

All parameters are optional, unless otherwise indicated.

user_id Retrieves all checkins for the given user. 1234
media_id Retrieves all checkins for the given media. 5678
max_id Retrieves all checkins before a given checkin id. 7891
since_id Retrieves all checkins after a given checkin id. 3456
count The total matching items to return (1-50). 25
Response

These are the body you can expect in the api response.

Array A list of Checkin objects (fields detailed below).

Create a checkin

POST http://gomiso.com/api/oauth/v1/checkins.json

Posts a new checkin to the specified media for the authenticated user.

Parameters

All parameters are optional, unless otherwise indicated.
If service parameters are omitted, defaults to user's checkin preferences.

media_id (Required) The specified media to create a checkin for. 1234
season_num The specified season to create a checkin for (if the media is a TV Show). 3
episode_num The specified episode to create a checkin for (if the media is a TV Show). 12
comment The attached message for this checkin. This is a great episode if you're a scrimshaw nut.
facebook Determines if the checkin should be posted to facebook. If this parameter is not specified, behavior defaults to the user's defaults. true
twitter Determines if the checkin should be posted to twitter. If this parameter is not specified, behavior defaults to the user's defaults. false
Response Fields

These are the fields you can expect in the response.

checkin The created check-in object (fields detailed below).

Object Representation

A Checkin object is represented with the following fields:

id The id for this checkin object. 9876
created_at The timestamp for when this checkin was created "2010-12-11T00:21:44Z"
comment The comment attached for this checkin. Dexter is a great show
replies_count The total number of replies for this checkin. 12
likes_count The total number of likes for this checkin. 6
user_id The user id for this checkin. 1234
user_username The user username for this checkin. john24
user_full_name The user name for this checkin. John Smith
user_profile_image_url The profile image for the given user. http://gomiso.com/uploads/BAhbCFsHOgZm.png
media_id The media id for this checkin. 5678
media_title The media title for this checkin. The Dark Knight
media_poster_url The poster image for the given media. http://gomiso.com/uploads/BAhbCFsHOgZm.png
media_poster_url_small The thumbnail poster image for the given media. http://gomiso.com/uploads/BAhbCFsHOgZm.png
episode_num The number of the episode checked into (if this is an episode checkin) 12
episode_season_num The number of the season the episode belonged to (if this is an episode checkin) 12
episode_label The label of the episode checked into (if this is an episode checkin) S03E12
episode_title The title of the episode checked into (if this is an episode checkin) It Takes Two to Tango
episode_poster_url The image url of the episode checked into (if this is an episode checkin) http://gomiso.com/abcdefg.jpg
episode_poster_url_small The thumbnail image url of the episode checked into (if this is an episode checkin) http://gomiso.com/abcdefg.jpg
badges An array of badges that were awarded with this checkin. Fields explained in badges section below. [{"name": "FancyPants", "category": "level", "id": 1234},{"name": "IdolFan", "category": "achievement", "id": 4321}]

Badges

Retrieve a list of badges

GET http://gomiso.com/api/oauth/v1/badges.json
GET http://gomiso.com/api/oauth/v1/badges/featured.json

Retrieves information about either the comprehensive set of badges or the badges in a specific category (ie badges/featured.json)

Parameters

All parameters are optional, unless otherwise indicated.

user_id The user id that you'd like applied to the badge list (badges that have already been awarded to that user will have a flag set) 1234
category The category of badges you'd like to display. This can be passed as part of the url (badges/featured.json) or as a separate param. The options are achievement, featured, and level featured
Response

This is the body you can expect in the api response.

Array A list of Badge objects (fields detailed below).
Error Conditions

These are the errors that are possible from this endpoint.

user_id 404 The user cannot be found.

Object Representation

A Badge object is represented with the following fields:

id The id of the badge. 3456
name The name that is displayed for the badge. TV Newbie
tagline A brief tagline associated with the badge and how it was won You sure do watch a lot of reality shows!
category The type of badge - level, achievement or featured level
hint Helpful advice about how to win the badge Check in to Family Guy 3000 times a day
awarded A boolean (true/false) flag explaining whether or not the given user has been awarded this badge true
graphic_url A url for the badge image http://gomiso.com/badge.jpg

Episodes

Retrieve episodes for a given media item

GET http://gomiso.com/api/oauth/v1/episodes.json

Retrieves a list of episodes for a given media item (TV Show)

Parameters

All parameters are optional, unless otherwise indicated.

media_id (Required) The media_id for the media to which the episodes you would like to retrieve belong. 1234
season_num The season for the episodes you would like to retrieve. If not specified returns all seasons. 3
count The total number of episodes you'd like to retrieve. 5
Response

These are the items you can expect in the api response.

episodes (Array) The matching episode objects [ episode: { episode fields } ]
episode_count The total number of episodes for the given media item 136
season_count The total number of seasons for the given media item 7
seasons The seasons for which we have episodes for the given media item (for cases where there is a season 0 and other anomalies) [0, 1, 2, 6]
Error Conditions

These are the errors that are possible from this endpoint.

media_id 404 The media cannot be found.

NOTE: Passing non-existant season_nums or episode_nums will return an empty response, NOT an error.

Retrieve episode information

GET http://gomiso.com/api/oauth/v1/episodes/show.json

Retrieves information about a specific episode. In the case of an ambiguous query, returns the most recent episode matching given parameters (for instance, if only a media_id and season_num are sent, the last episode of media_id for season_num is returned)

Parameters

All parameters are optional, unless otherwise indicated.

media_id (Required) The media_id for the episode you would like to retrieve. 1234
season_num The season for the episode you would like to retrieve. 3
episode_num The episode number of the given season you'd like to retrieve 12
Response

This is the item you can expect in the api response.

Episode The returned episode object { episode: episode fields }
Error Conditions

These are the errors that are possible from this endpoint.

media_id 404 The media cannot be found.
season_num 404 The episode cannot be found.
episode_num 404 The episode cannot be found.

Object Representation

An Episode object is represented with the basic following fields:

title The tile for this episode object The Big One
season_num The season during which this episode aired 3
episode_num The episode number with respect to the season during which this episode aired 12
aired The date the episode originally aired 2010-12-11T00:21:44Z
tvdb_id The tvdb id for the given episode 12345
label The season & episode label for the given episode S02E12
poster_image_url The poster image for this episode object http://gomiso.com/uploads/BAhbCFsHOgZm.png
poster_image_url_small The thumbnail poster image for this episode object http://gomiso.com/uploads/JHDkcDlskS.png
summary A short text description/synopsis of the episode Leo meets his real parents and is terrified to learn his father has halitosis.
cast Comma-delimited actors related to this media. Christian Bale, Heath Ledger

Notifications

Retrieve notifications

GET http://gomiso.com/api/oauth/v1/notifications.json

Retrieves a list of a user's notifications.

Parameters

This endpoint takes no parameters.

Response

These are the items you can expect in the api response.

Array The matching notification item objects (fields detailed below).
Error Conditions

This endpoint has no error codes.

Retrieve a single notification

GET http://gomiso.com/api/oauth/v1/notifications/show.json

Retrieves a single notification

Parameters

All parameters are optional, unless otherwise indicated.

notification_id (Required) The id for the notification you would like to retrieve. 1234
Response

This is the item you can expect in the api response.

notification_item The matching notification item object (fields detailed below).
Error Conditions

These are the errors that are possible from this endpoint.

notification_id 404 The notification cannot be found.

Object Representation

A Notification Item object is represented with the basic following fields:

id The id for the notification 1234
type The type of notification "comment"
description The text of the notification as it is displayed within the app. Steve Jones also replied to John Smith's post about The Big Bang Theory
created_at The date at which the notification was generated 2010-09-25T19: 14: 08Z
user A truncated user object representing the user responsible for the notifcation {username: "SteveHolt", full_name: "Steve Holt", url: "http://steve.io", tagline: "Steve Holt!", id: 1234, profile_image_url: "http://gomiso.com/steve.jpg"}

Extended details for notifications are

body If the notification is in reference to a comment, this will be the body of that comment I can't stand this movie!
feed_item_id The feed item associated with this notification (if there is one) 4567
topics An object representing the various objects associated with the notification (the media it refers to, etc) {media: (A full media object representation)}