<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: ZendX_Service_Rakuten Component Proposal

Table of Contents

1. Overview

ZendX_Service_Rakuten is a interface to use the "Rakuten Web service" that is provided by the Rakuten, Inc. .

2. References

The following links are API references written in Japanese. I write method names and brief description for each API.

• Rakuten Web Service
  • for the Rakuten Market
    • searchItem() - Search items. Uses ItemSearch API

      parameter	type	min	max	required	default	explanation
      						following in params array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      keyword	string			may required	null	key word. One of keyword, genreId or catalogCode is required
      shopCode	string				null	shop code
      genreId	int	0		may required	0	genre id. One of keyword, genreId or catalogCode is required.
      catalogCode	string			may required	null	catalog code. One of keyword, genreId or catalogCode is required
      hits	int	1	30		30	items per page.
      page	int	1	100		1	page limits.
      sort	string				standard	sort type. (mark)affiliateRate, (mark)reviewCount, (mark)itemPrice, (mark)updateTimestamp or standard. (mark) means plus or minus mark, each mark means Ascend and Descend. For example, +itemPrice
      minPrice	int	0			null	minimum price
      maxPrice	int	0			null	maximum price. It must be grater than minPrice
      availability	int	0	1		1	0:all items, 1:only items that can be bought
      field	int	0	1		1	0:search widely, 1:search narrowly
      carrier	int	0	1		0	0:PC, 1:mobile
      imageFlag	int	0	1		0	0:all item, 1:only items that has image
      orFlag	int	0	1		0	0:AND keywords, 1:OR keywords
      NGKeyword	string				null	keyword that you want to omit
      genreInformationFlag	int	0	1		0	No Use. 0:not get count of items that are in the same genre, 1:get count. This method supports only 0.

    • searchGenre() - Retrieve genre's information. Uses GenreSearch API

      parameter	type	min	max	required	default	explanation
      type	string			required	child	information type. child, parent or current
      genreId	int	0		required	0	genre id. If parent is specified, genre id must be grater than 0.
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      genrePath	int	0	1			No Use. genrePath is auto controlled in this method.

    • searchItemCode() - Retrieve item's information by item code. Uses ItemCodeSearch API

      parameter	type	min	max	required	default	explanation
      code	string			required		item code
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      carrier	int	0	1		0	0:PC, 1:mobile

    • searchCatalog() - Search items by catalog. Uses CatalogSearch API

      parameter	type	min	max	required	default	explanation
      						following in params array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      keyword	string			may required	null	key word. One of keyword or genreId is required
      genreId	int	0		may required	0	genre id. One of keyword or genreId is required.
      hits	int	1	30		30	items per page.
      page	int	1	100		1	page limits.
      sort	string				-registerDate	sort type. (mark)registerDate,(mark)releaseDate, (mark)reviewNum or random. (mark) means plus or minus mark, each mark means Ascend and Descend. For example, +reviewNum
      field	int	0	1		1	0:search widely, 1:search narrowly
      imageFlag	int	0	1		0	0:all item, 1:only items that has image
      releaseRange	int	0	12		0	0:no limit, 1-12:search only sold in specified months
      orFlag	int	0	1		0	0:AND keywords, 1:OR keywords
      NGKeyword	string				null	keyword that you want to omit
      genreInformationFlag	int	0	1		0	No use. cf. searchItem()

    • itemRanking() - Retrieve item ranking. Uses ItemRanking API

      parameter	type	min	max	required	default	explanation
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      genreId	int	0			null	genre id.
      age	int	10	50		null	age zone. 10:teen agers, 20:20 agers, 30:30 agers, 40:40 agers, 50:50 over
      sex	int	0	1		null	sex. 0:men, 1:women

  • for the Rakuten Books
    • searchBook() - search books. Uses BookSearch API

      parameter	type	min	max	required	default	explanation
      						following in params array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      keyword	string			may required	null	key word. One of keyword or genreId is required
      genreId	int	0		may required	0	genre id. One of keyword or genreId is required. The root id of the genreId must be 200162(books, magazine and comic).
      hits	int	1	30		30	items per page.
      page	int	1	100		1	page limits.
      sort	string				standard	sort type. (mark)affiliateRate, (mark)reviewCount, (mark)itemPrice, (mark)updateTimestamp or random. (mark) means plus or minus mark, each mark means Ascend and Descend. For example, +itemPrice
      minPrice	int	0			null	minimum price
      maxPrice	int	0			null	maximum price. It must be grater than minPrice.
      availability	int	0	1		1	0:all items, 1:only items that you can buy.
      field	int	0	1		1	0:search widely, 1:search narrowly
      carrier	int	0	1		0	0:PC, 1:mobile
      imageFlag	int	0	1		0	0:all item, 1:only items that has image
      orFlag	int	0	1		0	0:AND keywords, 1:OR keywords
      NGKeyword	string				null	keyword that you want to omit
      genreInformationFlag	int	0	1		0	No use. cf. searchItem()

    • searchCd() - search CDs. Uses CDSearch API
      This method has same parameters like searchBook(). But the root id of the genreId must be 101311(CD).
    • searchDvd() - search DVDs. Uses DVDSearch API
      This method has same parameters like searchBook(). But the root id of the genreId must be 101354(DVD).
  • for the Rakuten Auction
    • searchAuctionItem() - Search items. Uses AuctionItemSearch API

      parameter	type	min	max	required	default	explanation
      						following in params array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      keyword	string			may required	null	key word. One of keyword or genreId is required
      genreId	int	0		may required	0	genre id. One of keyword or genreId is required.
      hits	int	1	30		30	items per page.
      page	int	1	100		1	page limits.
      minPrice	int	0			null	minimum price
      maxPrice	int	0			null	maximum price. It must be grater than minPrice.
      sort	string				+endTime	sort type. (mark)endTime, (mark)itemPrice, (mark)bidCount or (mark)affiliateRate. (mark) means plus or minus mark, each mark means Ascend and Descend. For example, +itemPrice
      blowFlag	int	0	1		0	0:all items, 1:only items that you can buy without waiting auction's end.
      itemType	int	0	3		0	0:all items, 1:only items that are sold by personal seller, 2:only items that are sold by shops, 3:only items that are sold by auction shops
      newFlag	int	0	2		0	0:all items, 1:only used items, 2:only unused items
      field	int	0	1		1	0:search widely, 1:search narrowly
      carrier	int	0	1		0	0:PC, 1:mobile
      imageFlag	int	0	1		0	0:all item, 1:only items that has image
      orFlag	int	0	1		0	0:AND keywords, 1:OR keywords
      NGKeyword	string				null	keyword that you want to omit

    • searchAuctionItemCode() - Retrieve item's information by item code. Uses AuctionItemCodeSearch API

      parameter	type	min	max	required	default	explanation
      code	string			required		item code
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      carrier	int	0	1		0	0:PC, 1:mobile

  • for the Rakuten Travel
    • searchSimpleHotel() - Search hotels. Uses SimpleHotelSearch API

      parameter	type	min	max	required	default	explanation
      						following in params array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      largeClassCode	string			may required	null	area code. It specifies most wide area. For example, country. You can get the class codes list with getAreaClass(). One of the class codes set, hotelNo or latitude/longitude pair is required.
      middleClassCode	string			may required	null	area code. It is children of largeClassCode.
      smallClassCode	string			may required	null	area code. It is children of middleClassCode.
      detailClassCode	string			may required	null	area code. It is children of smallClassCode.
      hotelNo	integer			may required	null	hotel number. One of the class codes set, hotelNo or latitude/longitude pair is required.
      latitude	float			may required	null	latitude. One of the class codes set, hotelNo or latitude/longitude pair is required. Unit is specified with datumType.
      longitude	float			may required	null	longitude. Unit is specified with datumType.
      searchRadius	float	0.1	3.0		1.0	radius in searching. enable if you use the latitude/longitude pair. Unit is Km.
      squeezeCondition	string				null	condition of hotel. kinen?only hotels that have no smoking rooms, internet?only hotels where you can enjoy internet, daiyoku?only hotels that have swimming bath, onsen?only hotels that have hot springs.
      carrier	int	0	1		0	0:PC, 1:mobile
      hits	int				null	limit hit counts. enable if you use the latitude/longitude pair.
      datumType	int	1	2		2	1:Unit is degree, 2:Unit is second.

    • searchHotelDetail() - Retrieve hotel's information by hotel number. Uses HotelDetailSearch API

      parameter	type	min	max	required	default	explanation
      hotelNo	integer			required		hotel number
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      carrier	int	0	1		0	0:PC, 1:mobile
      datumType	int	1	2		2	1:Unit is degree, 2:Unit is second.

    • searchVacantHotel() - Search hotels that have vacant room. Uses VacantHotelSearch

      parameter	type	min	max	required	default	explanation
      type	string			required	hotel	information type. hotel or room.
      checkinDate	date			required	null	YYYY-MM-DD in Asia/Tokyo time zone.
      checkoutDate	date			required	null	YYYY-MM-DD in Asia/Tokyo time zone.
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      largeClassCode	string			may required	null	area code. It specifies most wide area. For example, country. You can get the class codes list with getAreaClass(). One of the class codes set, hotelNo or latitude/longitude pair is required.
      middleClassCode	string			may required	null	area code. It is children of largeClassCode.
      smallClassCode	string			may required	null	area code. It is children of middleClassCode.
      detailClassCode	string			may required	null	area code. It is children of smallClassCode.
      hotelNo	integer			may required	null	hotel number. One of the class codes set, hotelNo or latitude/longitude pair is required.
      adultNum	int	1	99		1	adult members count
      upClassNum	int	0	99		0	members count. The members are over elementary school higher students.
      lowClassNum	int	0	99		0	members count. The members are under elementary school lower students.
      infantWithMBNum	int	0	99		0	infant members count. They need foods and blankets.
      infantWithMNum	int	0	99		0	infant members count. They need only blankets.
      infantWithBNum	int	0	99		0	infant members count. They need only foods.
      infantWithoutMBNum	int	0	99		0	infant members count. They no need foods and blankets.
      roomNum	int	1	999		1	required room count
      maxCharge	int	0	9999999999		null	0:PC, 1:mobile. It must be grater than minCharge.
      minCharge	int	0	9999999999		null	0:PC, 1:mobile
      latitude	float			may required	null	latitude. One of the class codes set, hotelNo or latitude/longitude pair is required. Unit is specified with datumType.
      longitude	float			may required	null	longitude. Unit is specified with datumType.
      searchRadius	float	0.1	3.0		1.0	radius in searching. enable if you use the latitude/longitude pair. Unit is Km.
      squeezeCondition	string				null	condition of hotel. kinen?only hotels that have no smoking rooms, internet?only hotels where you can enjoy internet, daiyoku?only hotels that have swimming bath, onsen?only hotels that have hot springs, breakfast:only hotels where you can take breakfast, dinner:only hotels where you can take dinner.
      carrier	int	0	1		0	0:PC, 1:mobile
      datumType	int	1	2		2	1:Unit is degree, 2:Unit is second.
      hits	int				null	limit hit counts. enable if you use the latitude/longitude pair.

    • getAreaClass() - Retrieve choices of area. Uses GetAreaClass API

      parameter	type	min	max	required	default	explanation
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back

    • searchKeywordHotel() - Search hotels by word. Uses KeywordHotelSearch API

      parameter	type	min	max	required	default	explanation
      keyword	string			required		key word.
      						following in optparams array
      affiliateId	string				null	affiliate id
      callBack	string				null	function name of Json call back
      carrier	int	0	1		0	0:PC, 1:mobile
      page	int				1	page limits.
      hits	int	1	100		20	items per page.
      sumDisplayFlag	int	0	1		0	0:not display features about the area and the hotel, 1:display.
      middleClassCode	string				null	area code. You can get the list with getAreaClass().

  • Other purpose
    • dynamicAd() - Retrieve dynamic advertisements that is suitable for content in URL that you specify. Uses DynamicAd API and DynamicAd API (travel)

      parameter	type	min	max	required	default	explanation
      type	string			required	item	advertisement type. item or travel.
      affiliateId	string			required		affiliate id
      url	string			required		URL
      						following in optparams array
      carrier	int	0	1		0	0:PC, 1:mobile
      callBack	string				null	function name of Json call back

3. Component Requirements, Constraints, and Acceptance Criteria

• Implements the "Rakuten Web Service" APIs.
• Returns server responses as lightweight data objects.

4. Dependencies on Other Framework Components

• Zend_Rest_Client
• Zend_Service_Exception

5. Theory of Operation

Returns server response as the SimpleXMLElement.

6. Milestones / Tasks

• Milestone 1: Class development and write proposal
• Milestone 2: Unit tests and debugging
• Milestone 3: Documentation

7. Class Index

• ZendX_Service_Rakuten

8. Use Cases

Search 3 items by word, "Zend Studio". Its case is most simple case.

Retrieve hotels that have vacant room for 1 adult person in the kasukabe city from today to tommorow.
The kasukabe city is in the saitama ward, and the saitama ward is in japan.
The checkinDate and checkoutDate are in Asia/Tokyo (GMT +9) time zone.

Display advertisements that is suitable for www.zend.com .
dynamicAd() needs your affiliate ID from the Rakuten web service.

9. Class Skeletons