">mixi Developer Center (mDC)

mixi Connect

mixi Connect (English) » mixi Graph API » Technical Specification » Calendar API

Calendar API

The calendar can hold not only a user's past and future plans, but also information such as when and who they spent time doing what. The Calendar API makes it possible to easily use this information for various situations.

This document explains how to use the Calendar API.

Prerequisites

To use the Calendar API, you are required to have the following information beforehand.

  • An access token authorized for either or both the “r_calendar” and ”w_calendar” scopes

You can only access the Calendar API with an authorized access token as mentioned above. For details on how to obtain an access token, see the page on the “procedures for authorization”.

Functions provided by the Calendar API, and the necessary scope

The various functions provided by the Calendar API fall into the following two major groups: reading and writing. This classification directly corresponds to the scopes for using the Calendar API. The following shows the scopes and corresponding functions:

Scope Function
r_calendar Obtaining the dated schedules
w_calendar Adding a dated schedule
* Currently it's not possible to read or write schedules that don't have a fixed date.

Obtaining a schedule (using an ID)

The following URI is for retrieving a specific schedule using its ID.

GET https://api.mixi-platform.com/2/calendar/schedules/[User-ID]/@self/[Schedule-ID]
Parameter name Value to be specified
User-ID User ID for the approved user or “@me”, or a friend's user ID. Specify the schedule's owner.
Schedule-ID A schedule's ID

In addition, the query parameters below are supported:

Parameter name Description
fields Specify the fields you want information for, separated by a comma. Specifiable field names are: “description,​privacy,​owner,​owner.thumbnailUrl,​owner.profileUrl,​attendees,​attendees.thumbnailUrl,​attendees.profileUrl”. If the default for the fields parameter is set, all fields are considered specified. “start_time” and “title” will always be included in the result. Also, “owner” and “attendees” implicitly include “owner.id,owner.displayName” and “attendees.id,attendees.displayName” respectively.

On a successful request, the result will be similar to the following.

{
  "entry":{
    "id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "start_time":"2012-01-01T00:00:00+09:00",
    "title":"New Year",
    "description":"Happy New Year!",
    "privacy":{
      "visibility":"public"
    },
    "owner":{
      "id":"xxxxxxxxxxxxx",
      "displayName":"Nickname",
      "thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
      "profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
    },
    "attendees":[
      {  
        "id":"xxxxxxxxxxxxx",
        "displayName":"Nickname",
        "thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
        "profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
      },
      ..cont'd..
    ]  
  }
}

Each entry contains the following information:

Field name Description
id ID (Schedule-ID) to identify the schedule
startDatetime The schedule's start date and time.
title Title
description Description
privacy The schedule's privacy setting. See below for details.
owner Schedule owner
owner.id Schedule owner's ID
owner.displayName Schedule owner's nickname
owner.thumbnailUrl Schedule owner's profile photo URL
owner.profileUrl Schedule owner's profile page URL
attendees Attendees (Array)
attendees.id An attendee's ID
attendees.displayName An attendee's nickname
attendees.thumbnailUrl An attendee's profile photo URL
attendees.profileUrl An attendee's profile page URL

* When the schedule's “owner” is not a friend, the “thumbnailUrl” and “profileUrl” fields are not returned, regardless of the “fields” parameter. Also, “attendees” only includes friends.

Format of “privacy” parameter

A schedule's privacy setting is defined in its “privacy” parameter. The “privacy” parameter contains a “visibility” parameter, which holds one of the following values.

Specified valueDescription
everyoneVisible to everyone
friendsVisible to friends
friends_of_friendsVisible to friends of friends
top_friendsVisible to good friends
groupVisible to a specific group
userVisible to specific users
access_keyVisible to those who know a password
selfNot visible

Obtaining a list of schedules (for a specified span)

The following URI is for retrieving schedules from a specific start date.

GET https://api.mixi-platform.com/2/calendar/schedules/[User-ID]/[Group-ID]?startDatetimeMin=[DATETIME]
Parameter name Value to be specified
User-ID User ID for the approved user or “@me”, or a friend's user ID. Specify the schedule's owner.
Group-ID “@self” or “@friends” or “@all”

* It's not possible to retrieve a schedule posted by a friend of a friend. For example, this results in an error: /calendar/schedule/[a friend's UID]/@friends

In addition, the query parameters below are supported:

Parameter name Description
startDatetimeMin The start date's minimum value. Required parameter. Please use w3cdtf-format.
startDatetimeMax The start date's maximum value. Please use w3cdtf-format. When omitted, it defaults to 25:59:59 of the date specified in startDatetimeMin.
fields Specify the fields you want information for, separated by a comma. Specifiable field names are: “description,​privacy,​owner,​owner.thumbnailUrl,​owner.profileUrl,​attendees,​attendees.thumbnailUrl,​attendees.profileUrl”. If the default for the fields parameter is set, “privacy,​owner,​owner.thumbnailUrl,​owner.profileUrl” fields are considered specified. “start_time” and “title” will always be included in the result. Also, “owner” and “attendees” implicitly include “owner.id,owner.displayName” and “attendees.id,attendees.displayName” respectively.

On a successful request, the result will be similar to the following.

{
  "entry":[
    {  
      "id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "start_time":"2012-01-01T00:00:00+09:00",
      "title":"New Year",
      "description":"Happy New Year!",
      "privacy":{
        "visibility":"public"
      },
      "owner":{
        "id":"xxxxxxxxxxxxx",
        "displayName":"Nickname",
        "thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
        "profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
      },
      "attendees":[
        {  
          "id":"xxxxxxxxxxxxx",
          "displayName":"Nickname",
          "thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
          "profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
        },
        ..cont'd..
      ],
    },
    ..cont'd..
}

Each entry contains the following information:

Field name Description
id ID (Schedule-ID) to identify the schedule
startDatetime The schedule's start date and time.
title Title
description Description
privacy The schedule's privacy setting. See below for details.
owner Schedule owner
owner.id Schedule owner's ID
owner.displayName Schedule owner's nickname
owner.thumbnailUrl Schedule owner's profile photo URL
owner.profileUrl Schedule owner's profile page URL
attendees Attendees (Array)
attendees.id An attendee's ID
attendees.displayName An attendee's nickname
attendees.thumbnailUrl An attendee's profile photo URL
attendees.profileUrl An attendee's profile page URL

* When the schedule's “owner” is not a friend, the “thumbnailUrl” and “profileUrl” fields are not returned, regardless of the “fields” parameter. Also, “attendees” only includes friends.

Creating a schedule

The following URI is for creating a schedule.

POST https://api.mixi-platform.com/2/calendar/schedules/[User-ID]/@self
Parameter name Value to be specified
User-ID User ID for the approved user or “@me”.

Set the Content-Type request header to “application/json”, and include the schedule in JSON format in the request body as shown below.

{
  "startDatetimes":"2012-01-01T00:00:00+09:00",
  "title":"New Year",
  "description":"Happy New Year!",
  "invite":"0",
  "privacy":{
    "visibility":"everyone"
  },
  "attendees":[
    "member0001",
    "member0002",
    "member0003"
  ]
}

* “invite” specifies whether other users can attend.

Upon success, the response has a status code of 201 and the new schedule's ID is returned in JSON format as follows.

{
    "id" : "73a1354313a8dced1ca07a68c1204b3d727042d048"
}

TOP OF THIS PAGE