Search: list

แสดงผลคอลเล็กชันของผลการค้นหาที่ตรงกับพารามิเตอร์การค้นหาที่ระบุในคำขอ API โดยค่าเริ่มต้น ชุดผลการค้นหาจะระบุทรัพยากร video, channel และ playlist ที่ตรงกัน แต่คุณยังกำหนดค่าการค้นหาให้ดึงข้อมูลทรัพยากรประเภทใดประเภทหนึ่งโดยเฉพาะได้ด้วย

ผลกระทบต่อโควต้า: 100 การเรียกต่อวัน การเรียกใช้เมธอดนี้มีค่าใช้จ่ายโควต้า 1 หน่วยในที่เก็บโควต้าของคำค้นหา

กรณีการใช้งานทั่วไป

ส่งคำขอ

คำขอ HTTP

GET https://www.googleapis.com/youtube/v3/search

พารามิเตอร์

ตารางต่อไปนี้แสดงพารามิเตอร์ที่การค้นหานี้รองรับ พารามิเตอร์ทั้งหมดที่แสดงเป็นพารามิเตอร์การค้นหา

พารามิเตอร์
พารามิเตอร์ที่จำเป็น
part string
พารามิเตอร์ part ระบุรายการพร็อพเพอร์ตี้ทรัพยากร search อย่างน้อย 1 รายการที่คั่นด้วยคอมมา ซึ่งการตอบกลับจาก API จะรวมไว้ด้วย ตั้งค่าพารามิเตอร์เป็น snippet
ตัวกรอง (ระบุพารามิเตอร์ต่อไปนี้ 0 หรือ 1 รายการ)
forContentOwner boolean
พารามิเตอร์นี้ใช้ได้เฉพาะในคำขอที่ได้รับอนุญาตอย่างถูกต้อง และมีไว้สำหรับพาร์ทเนอร์เนื้อหาของ YouTube โดยเฉพาะ

พารามิเตอร์ forContentOwner จะจำกัดการค้นหาให้ดึงเฉพาะวิดีโอที่เป็นของเจ้าของเนื้อหาที่ระบุโดยพารามิเตอร์ onBehalfOfContentOwner เท่านั้น หากตั้งค่า forContentOwner เป็น "จริง" คำขอต้องเป็นไปตามข้อกำหนดต่อไปนี้ด้วย
  • ต้องระบุพารามิเตอร์ onBehalfOfContentOwner
  • ผู้ใช้ที่ให้สิทธิ์คำขอต้องใช้บัญชีที่ลิงก์กับเจ้าของเนื้อหาที่ระบุ
  • ต้องตั้งค่าพารามิเตอร์ type เป็น video
  • คุณจะตั้งค่าพารามิเตอร์อื่นๆ ต่อไปนี้ไม่ได้ videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoPaidProductPlacement, videoSyndicated, videoType
forDeveloper boolean
พารามิเตอร์นี้ใช้ได้เฉพาะในคำขอที่ได้รับอนุญาตอย่างถูกต้องเท่านั้น พารามิเตอร์ forDeveloper จะจำกัดการค้นหาให้ดึงเฉพาะวิดีโอที่อัปโหลดผ่านแอปพลิเคชันหรือเว็บไซต์ของนักพัฒนาซอฟต์แวร์เท่านั้น เซิร์ฟเวอร์ API จะใช้ข้อมูลเข้าสู่ระบบการให้สิทธิ์ของคำขอเพื่อระบุนักพัฒนาแอป คุณใช้พารามิเตอร์ forDeveloper ร่วมกับพารามิเตอร์การค้นหาที่ไม่บังคับได้ เช่น พารามิเตอร์ q

สำหรับฟีเจอร์นี้ วิดีโอที่อัปโหลดแต่ละรายการจะได้รับการติดแท็กโดยอัตโนมัติด้วยหมายเลขโปรเจ็กต์ที่เชื่อมโยงกับแอปพลิเคชันของนักพัฒนาแอปใน Google Developers Console

เมื่อคำขอค้นหาตั้งค่าพารามิเตอร์ forDeveloper เป็น true ในภายหลัง เซิร์ฟเวอร์ API จะใช้ข้อมูลเข้าสู่ระบบการให้สิทธิ์ของคำขอเพื่อระบุนักพัฒนาแอป ดังนั้น นักพัฒนาแอปจึงสามารถจำกัดผลการค้นหาให้แสดงเฉพาะวิดีโอที่อัปโหลดผ่านแอปหรือเว็บไซต์ของนักพัฒนาแอปเอง แต่จะจำกัดวิดีโอที่อัปโหลดผ่านแอปหรือเว็บไซต์อื่นๆ ไม่ได้
forMine boolean
พารามิเตอร์นี้ใช้ได้เฉพาะในคำขอที่ได้รับอนุญาตอย่างถูกต้องเท่านั้น พารามิเตอร์ forMine จะจำกัดการค้นหาให้ดึงข้อมูลเฉพาะวิดีโอที่ผู้ใช้ที่ตรวจสอบสิทธิ์แล้วเป็นเจ้าของ หากตั้งค่าพารามิเตอร์นี้เป็น true คุณจะต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย นอกจากนี้ คุณยังตั้งค่าพารามิเตอร์อื่นๆ ต่อไปนี้ในคำขอเดียวกันไม่ได้ videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoPaidProductPlacement, videoSyndicated, videoType
พารามิเตอร์ที่ไม่บังคับ
channelId string
พารามิเตอร์ channelId บ่งชี้ว่าการตอบกลับจาก API ควรมีเฉพาะทรัพยากรที่สร้างโดยช่องเท่านั้น

หมายเหตุ: ผลการค้นหาจะถูกจำกัดไว้ที่วิดีโอสูงสุด 500 รายการหากคำขอของคุณระบุค่าสำหรับพารามิเตอร์ channelId และตั้งค่าพารามิเตอร์ type เป็น video แต่ไม่ได้ตั้งค่าตัวกรอง forContentOwner, forDeveloper หรือ forMine ตัวใดตัวหนึ่งด้วย
channelType string
พารามิเตอร์ channelType ช่วยให้คุณจำกัดการค้นหาให้แสดงเฉพาะช่องประเภทใดประเภทหนึ่ง

ค่าที่ยอมรับได้มีดังนี้
  • any – แสดงผลช่องทั้งหมด
  • show – ดึงข้อมูลรายการเท่านั้น
eventType string
พารามิเตอร์ eventType จะจำกัดการค้นหาเฉพาะกิจกรรมการออกอากาศ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • completed – รวมเฉพาะการออกอากาศที่เสร็จสมบูรณ์แล้ว
  • live – รวมเฉพาะการออกอากาศที่ใช้งานอยู่
  • upcoming – รวมเฉพาะการออกอากาศที่กำลังจะเกิดขึ้น
location string
พารามิเตอร์ location ร่วมกับพารามิเตอร์ locationRadius จะกำหนดพื้นที่ทางภูมิศาสตร์แบบวงกลม และยังจำกัดการค้นหาวิดีโอที่ระบุสถานที่ตั้งทางภูมิศาสตร์ที่อยู่ในพื้นที่นั้นในข้อมูลเมตาด้วย ค่าพารามิเตอร์คือสตริงที่ระบุพิกัดละติจูด/ลองจิจูด เช่น (37.42307,-122.08427)

  • ค่าพารามิเตอร์ location จะระบุจุดที่ศูนย์กลางของพื้นที่
  • พารามิเตอร์ locationRadius จะระบุระยะทางสูงสุดที่สถานที่ตั้งซึ่งเชื่อมโยงกับวิดีโอสามารถอยู่ห่างจากจุดนั้นได้ เพื่อให้วิดีโอยังคงรวมอยู่ในผลการค้นหา
API จะแสดงข้อผิดพลาดหากคำขอของคุณระบุค่าสำหรับพารามิเตอร์ location แต่ไม่ได้ระบุค่าสำหรับพารามิเตอร์ locationRadius ด้วย

หมายเหตุ: หากคุณระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย
locationRadius string
พารามิเตอร์ locationRadius จะกำหนดพื้นที่ทางภูมิศาสตร์ที่เป็นวงกลมร่วมกับพารามิเตอร์ location

ค่าพารามิเตอร์ต้องเป็นเลขทศนิยมตามด้วยหน่วยวัด หน่วยวัดที่ถูกต้องคือ m, km, ft และ mi ตัวอย่างเช่น ค่าพารามิเตอร์ที่ถูกต้อง ได้แก่ 1500m, 5km, 10000ft และ 0.75mi API ไม่รองรับค่าพารามิเตอร์ locationRadius ที่มากกว่า 1,000 กิโลเมตร

หมายเหตุ: ดูข้อมูลเพิ่มเติมได้ที่คําจํากัดความของพารามิเตอร์ location
maxResults unsigned integer
พารามิเตอร์ maxResults จะระบุจำนวนรายการสูงสุดที่ควรแสดงในชุดผลลัพธ์ ค่าที่ยอมรับได้คือ 0 ถึง 50 ค่าเริ่มต้นคือ 5
onBehalfOfContentOwner string
พารามิเตอร์นี้ใช้ได้เฉพาะในคำขอที่ได้รับอนุญาตอย่างถูกต้องเท่านั้น หมายเหตุ: พารามิเตอร์นี้มีไว้สำหรับพาร์ทเนอร์เนื้อหา YouTube เท่านั้น

พารามิเตอร์ onBehalfOfContentOwner บ่งชี้ว่าข้อมูลเข้าสู่ระบบการให้สิทธิ์ของคำขอระบุผู้ใช้ YouTube CMS ที่ดำเนินการในนามของเจ้าของเนื้อหาที่ระบุไว้ในค่าพารามิเตอร์ พารามิเตอร์นี้มีไว้สำหรับพาร์ทเนอร์เนื้อหา YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube หลายช่อง ซึ่งช่วยให้เจ้าของเนื้อหาทำการตรวจสอบสิทธิ์เพียงครั้งเดียวและเข้าถึงข้อมูลวิดีโอและช่องทั้งหมดได้โดยไม่ต้องระบุข้อมูลรับรองการตรวจสอบสิทธิ์สำหรับแต่ละช่อง บัญชี CMS ที่ผู้ใช้ตรวจสอบสิทธิ์ด้วยต้องลิงก์กับเจ้าของเนื้อหา YouTube ที่ระบุ
order string
พารามิเตอร์ order ระบุเมธอดที่จะใช้ในการจัดลำดับทรัพยากรในการตอบกลับจาก API ค่าเริ่มต้นคือ relevance

ค่าที่ยอมรับได้มีดังนี้
  • date – ระบบจะจัดเรียงทรัพยากรตามลำดับเวลาย้อนกลับโดยอิงตามวันที่สร้าง หมายเหตุ: เนื่องจากฟีเจอร์นี้อาศัยดัชนีของ Search คุณจึงอาจพบว่าการจัดทำดัชนีเนื้อหาใหม่ล่าช้าหรือได้รับชุดผลลัพธ์ที่ไม่สมบูรณ์ หากต้องการดึงข้อมูลวิดีโอที่อัปโหลดล่าสุดของช่องอย่างน่าเชื่อถือ โปรดอย่าใช้ search.list แต่ให้ใช้เมธอด playlistItems.list เพื่อดึงข้อมูลเพลย์ลิสต์การอัปโหลดของช่องแทน
  • rating – แหล่งข้อมูลจะจัดเรียงตามคะแนนจากสูงสุดไปต่ำสุด หมายเหตุ: การจัดอันดับนี้คำนวณโดยใช้คะแนนอัลกอริทึมภายใน และไม่เทียบเท่ากับจำนวนการกดชอบที่เรียงจากมากไปน้อยอย่างเคร่งครัด
  • relevance – ระบบจะจัดเรียงแหล่งข้อมูลตามความเกี่ยวข้องกับคำค้นหา นี่เป็นค่าเริ่มต้นสำหรับพารามิเตอร์นี้
  • title – แหล่งข้อมูลจะจัดเรียงตามตัวอักษรของชื่อ
  • videoCount – ช่องจะจัดเรียงตามจำนวนวิดีโอที่อัปโหลดจากมากไปน้อย
  • viewCount – แหล่งข้อมูลจะจัดเรียงตามจำนวนการดูจากมากที่สุดไปน้อยที่สุด สำหรับการถ่ายทอดสด ระบบจะจัดเรียงวิดีโอตามจำนวนผู้ชมที่ดูพร้อมกันขณะที่การถ่ายทอดสดยังดำเนินอยู่
pageToken string
พารามิเตอร์ pageToken จะระบุหน้าเว็บที่เฉพาะเจาะจงในชุดผลลัพธ์ที่ควรแสดงผล ในการตอบกลับจาก API พร็อพเพอร์ตี้ nextPageToken และ prevPageToken จะระบุหน้าอื่นๆ ที่สามารถดึงข้อมูลได้
publishedAfter datetime
พารามิเตอร์ publishedAfter ระบุว่าการตอบกลับจาก API ควรมีเฉพาะทรัพยากรที่สร้างขึ้น ณ เวลาที่ระบุหรือหลังจากนั้น ค่านี้เป็นค่าวันที่และเวลาในรูปแบบ RFC 3339 (1970-01-01T00:00:00Z)
publishedBefore datetime
พารามิเตอร์ publishedBefore บ่งชี้ว่าการตอบกลับจาก API ควรมีเฉพาะทรัพยากรที่สร้างขึ้นก่อนหรือ ณ เวลาที่ระบุเท่านั้น ค่านี้คือค่าวันที่และเวลาในรูปแบบ RFC 3339 (1970-01-01T00:00:00Z)
q string
พารามิเตอร์ q จะระบุคำค้นหาที่ต้องการค้นหา

คำขอของคุณยังใช้โอเปอเรเตอร์บูลีน NOT (-) และ OR (|) เพื่อยกเว้นวิดีโอหรือค้นหาวิดีโอที่เชื่อมโยงกับข้อความค้นหาอย่างน้อย 1 รายการได้ด้วย ตัวอย่างเช่น หากต้องการค้นหาวิดีโอที่ตรงกับ "boating" หรือ "sailing" ให้ตั้งค่าพารามิเตอร์ q เป็น boating|sailing ในทำนองเดียวกัน หากต้องการค้นหาวิดีโอที่ตรงกับ "boating" หรือ "sailing" แต่ไม่ใช่ "fishing" ให้ตั้งค่าพารามิเตอร์ q เป็น boating|sailing -fishing โปรดทราบว่าต้องกำหนดอักขระไปป์เป็นอักขระหลีกของ URL เมื่อส่งในคำขอ API ค่าที่หลีกเลี่ยง URL สำหรับอักขระไปป์คือ %7C
regionCode string
พารามิเตอร์ regionCode จะสั่งให้ API แสดงผลการค้นหาวิดีโอที่ดูได้ในประเทศที่ระบุ ค่าพารามิเตอร์คือรหัสประเทศ ISO 3166-1 alpha-2
relevanceLanguage string
พารามิเตอร์ relevanceLanguage จะสั่งให้ API แสดงผลการค้นหาที่เกี่ยวข้องกับภาษาที่ระบุมากที่สุด โดยปกติแล้ว ค่าพารามิเตอร์จะเป็นรหัสภาษา ISO 639-1 แบบ 2 ตัวอักษร อย่างไรก็ตาม คุณควรใช้ค่า zh-Hans สำหรับภาษาจีนตัวย่อ และ zh-Hant สำหรับภาษาจีนตัวเต็ม โปรดทราบว่าระบบจะยังคงแสดงผลการค้นหาในภาษาอื่นๆ หากมีความเกี่ยวข้องอย่างมากกับคำค้นหา
safeSearch string
พารามิเตอร์ safeSearch จะระบุว่าผลการค้นหาควรมีเนื้อหาที่ถูกจำกัดและเนื้อหามาตรฐานหรือไม่

ค่าที่ยอมรับมีดังนี้
  • moderate – YouTube จะกรองเนื้อหาบางส่วนออกจากผลการค้นหา และอย่างน้อยที่สุดจะกรองเนื้อหาที่ถูกจำกัดในพื้นที่ของคุณ เราอาจนำผลการค้นหาออกจากผลการค้นหาหรือลดอันดับในผลการค้นหา ทั้งนี้ขึ้นอยู่กับเนื้อหา นี่คือค่าพารามิเตอร์เริ่มต้น
  • none – YouTube จะไม่กรองชุดผลการค้นหา
  • strict – YouTube จะพยายามยกเว้นเนื้อหาที่ถูกจำกัดทั้งหมดออกจากชุดผลการค้นหา ระบบอาจนำผลการค้นหาออกจากผลการค้นหาหรือลดอันดับในผลการค้นหา ทั้งนี้ขึ้นอยู่กับเนื้อหาของผลการค้นหา
topicId string
พารามิเตอร์ topicId บ่งชี้ว่าการตอบกลับจาก API ควรมีเฉพาะทรัพยากรที่เชื่อมโยงกับหัวข้อที่ระบุเท่านั้น ค่านี้ระบุรหัสหัวข้อ Freebase

สำคัญ: เนื่องจากมีการเลิกใช้งาน Freebase และ Freebase API พารามิเตอร์ topicId จึงเริ่มทำงานแตกต่างออกไปตั้งแต่วันที่ 27 กุมภาพันธ์ 2017 ในตอนนั้น YouTube เริ่มรองรับชุดรหัสหัวข้อที่คัดสรรมาแล้วจำนวนเล็กน้อย และคุณจะใช้ได้เฉพาะรหัสชุดเล็กๆ นั้นเป็นค่าสำหรับพารามิเตอร์นี้
type string
พารามิเตอร์ type จะจำกัดคำค้นหาให้ดึงข้อมูลเฉพาะทรัพยากรประเภทใดประเภทหนึ่งเท่านั้น ค่าคือรายการประเภททรัพยากรที่คั่นด้วยคอมมา ค่าเริ่มต้นคือ video,channel,playlist

ค่าที่ยอมรับได้มีดังนี้
  • channel
  • playlist
  • video
videoCaption string
พารามิเตอร์ videoCaption จะระบุว่า API ควรกรองผลการค้นหาวิดีโอโดยอิงตามว่าวิดีโอมีคำบรรยายแทนเสียงหรือไม่ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – ไม่กรองผลการค้นหาตามความพร้อมใช้งานของคำบรรยายแทนเสียง
  • closedCaption – แสดงเฉพาะวิดีโอที่มีคำบรรยายแทนเสียง
  • none – รวมเฉพาะวิดีโอที่ไม่มีคำบรรยายแทนเสียง
videoCategoryId string
พารามิเตอร์ videoCategoryId จะกรองผลการค้นหาวิดีโอตามหมวดหมู่ของวิดีโอ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย
videoDefinition string
พารามิเตอร์ videoDefinition ช่วยให้คุณจำกัดการค้นหาให้รวมเฉพาะวิดีโอความละเอียดสูง (HD) หรือความละเอียดมาตรฐาน (SD) วิดีโอความละเอียดสูงจะเล่นได้ที่ความละเอียดอย่างน้อย 720p แต่อาจเล่นที่ความละเอียดสูงกว่านั้นได้ด้วย เช่น 1080p หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – แสดงวิดีโอทั้งหมด ไม่ว่าวิดีโอจะมีความละเอียดเท่าใดก็ตาม
  • high – ดึงข้อมูลเฉพาะวิดีโอความละเอียดสูง
  • standard - ดึงข้อมูลเฉพาะวิดีโอในความละเอียดมาตรฐาน
videoDimension string
พารามิเตอร์ videoDimension ช่วยให้คุณจำกัดการค้นหาให้ดึงข้อมูลเฉพาะวิดีโอ 2 มิติหรือ 3 มิติได้ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับมีดังนี้
  • 2d – จำกัดผลการค้นหาเพื่อยกเว้นวิดีโอ 3 มิติ
  • 3d – จำกัดผลการค้นหาให้มีเฉพาะวิดีโอ 3 มิติ
  • any - รวมทั้งวิดีโอ 3 มิติและวิดีโอที่ไม่ใช่ 3 มิติในผลการค้นหาที่แสดงผล นี่คือค่าเริ่มต้น
videoDuration string
พารามิเตอร์ videoDuration จะกรองผลการค้นหาวิดีโอตามระยะเวลาของวิดีโอ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – ไม่กรองผลการค้นหาวิดีโอตามระยะเวลา นี่คือค่าเริ่มต้น
  • long – รวมเฉพาะวิดีโอที่ยาวกว่า 20 นาที
  • medium – รวมเฉพาะวิดีโอที่มีความยาวระหว่าง 4-20 นาที (รวมทั้ง 2 ค่า)
  • short – ใส่เฉพาะวิดีโอที่มีความยาวไม่เกิน 4 นาที
videoEmbeddable string
พารามิเตอร์ videoEmbeddable ช่วยให้คุณจำกัดการค้นหาให้แสดงเฉพาะวิดีโอที่ฝังลงในหน้าเว็บได้ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – แสดงวิดีโอทั้งหมด ไม่ว่าจะฝังได้หรือไม่ก็ตาม
  • true – ดึงข้อมูลเฉพาะวิดีโอที่ฝังได้
videoLicense string
พารามิเตอร์ videoLicense จะกรองผลการค้นหาเพื่อรวมเฉพาะวิดีโอที่มีใบอนุญาตเฉพาะ YouTube อนุญาตให้ผู้อัปโหลดวิดีโอเลือกแนบสัญญาอนุญาตครีเอทีฟคอมมอนส์ (Creative Commons License) หรือสัญญาอนุญาตฉบับมาตรฐานของ YouTube กับวิดีโอแต่ละรายการได้ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – แสดงวิดีโอทั้งหมดที่ตรงกับพารามิเตอร์การค้นหา ไม่ว่าวิดีโอจะมีใบอนุญาตใดก็ตาม
  • creativeCommon – แสดงเฉพาะวิดีโอที่มีสัญญาอนุญาตครีเอทีฟคอมมอนส์ (Creative Commons License) ผู้ใช้สามารถนำวิดีโอที่มีใบอนุญาตนี้ไปใช้ซ้ำในวิดีโออื่นๆ ที่สร้างได้ ดูข้อมูลเพิ่มเติม
  • youtube – แสดงเฉพาะวิดีโอที่มีสัญญาอนุญาตฉบับมาตรฐานของ YouTube
videoPaidProductPlacement string
พารามิเตอร์ videoPaidProductPlacement จะกรองผลการค้นหาให้รวมเฉพาะวิดีโอที่ครีเอเตอร์ระบุว่ามีการโปรโมตแบบเสียค่าใช้จ่าย หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – แสดงวิดีโอทั้งหมด ไม่ว่าจะมีหรือไม่มีการโปรโมตแบบเสียค่าใช้จ่ายก็ตาม
  • true – ดึงข้อมูลเฉพาะวิดีโอที่มีการโปรโมตแบบเสียค่าใช้จ่าย
videoSyndicated string
พารามิเตอร์ videoSyndicated ช่วยให้คุณจำกัดการค้นหาเฉพาะวิดีโอที่เล่นนอก youtube.com ได้ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – แสดงวิดีโอทั้งหมด ไม่ว่าจะมีการเผยแพร่ซ้ำหรือไม่ก็ตาม
  • true – ดึงข้อมูลเฉพาะวิดีโอที่เผยแพร่
videoType string
พารามิเตอร์ videoType ช่วยให้คุณจำกัดการค้นหาให้แสดงเฉพาะวิดีโอประเภทใดประเภทหนึ่งได้ หากระบุค่าสำหรับพารามิเตอร์นี้ คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย

ค่าที่ยอมรับได้มีดังนี้
  • any – แสดงวิดีโอทั้งหมด
  • episode – ดึงข้อมูลเฉพาะตอนของรายการ
  • movie – ดึงข้อมูลภาพยนตร์เท่านั้น

เนื้อความของคำขอ

อย่าระบุเนื้อหาคำขอเมื่อเรียกใช้เมธอดนี้

คำตอบ

หากทำสำเร็จ เมธอดนี้จะแสดงผลเนื้อหาการตอบกลับซึ่งมีโครงสร้างดังต่อไปนี้

{
  "kind": "youtube#searchListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "regionCode": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    search Resource
  ]
}

พร็อพเพอร์ตี้

ตารางต่อไปนี้จะกำหนดพร็อพเพอร์ตี้ที่ปรากฏในผลการค้นหา

พร็อพเพอร์ตี้
kind string
ระบุประเภทของทรัพยากร API ค่าจะเป็น youtube#searchListResponse
etag etag
Etag ของทรัพยากรนี้
nextPageToken string
โทเค็นที่ใช้เป็นค่าของพารามิเตอร์ pageToken เพื่อดึงข้อมูลหน้าถัดไปในชุดผลลัพธ์ได้
prevPageToken string
โทเค็นที่ใช้เป็นค่าของพารามิเตอร์ pageToken เพื่อดึงข้อมูลหน้าก่อนหน้าในชุดผลลัพธ์ได้
regionCode string
รหัสภูมิภาคที่ใช้สำหรับคำค้นหา ค่าพร็อพเพอร์ตี้คือรหัสประเทศ ISO แบบ 2 ตัวอักษรที่ระบุภูมิภาค เมธอด i18nRegions.list จะแสดงรายการภูมิภาคที่รองรับ ค่าเริ่มต้นคือ US หากมีการระบุภูมิภาคที่ไม่รองรับ YouTube อาจยังคงเลือกภูมิภาคอื่นแทนค่าเริ่มต้นเพื่อจัดการคำค้นหา
pageInfo object
ออบเจ็กต์ pageInfo จะรวมข้อมูลการแบ่งหน้าสำหรับชุดผลลัพธ์
pageInfo.totalResults integer
จำนวนผลลัพธ์ทั้งหมดในชุดผลลัพธ์ โปรดทราบว่าค่านี้เป็นค่าประมาณและอาจไม่ใช่ค่าที่แน่นอน นอกจากนี้ ค่าสูงสุดคือ 1,000,000

คุณไม่ควรใช้ค่านี้เพื่อสร้างลิงก์การแบ่งหน้า ให้ใช้ค่าพร็อพเพอร์ตี้ nextPageToken และ prevPageToken แทนเพื่อพิจารณาว่าจะแสดงลิงก์การแบ่งหน้าหรือไม่
pageInfo.resultsPerPage integer
จํานวนผลลัพธ์ที่รวมอยู่ในการตอบกลับจาก API
items[] list
รายการผลลัพธ์ที่ตรงกับเกณฑ์การค้นหา

ตัวอย่าง

หมายเหตุ: ตัวอย่างโค้ดต่อไปนี้อาจไม่ได้แสดงถึงภาษาโปรแกรมที่รองรับทั้งหมด ดูรายการภาษาที่รองรับได้ในเอกสารประกอบไลบรารีของไคลเอ็นต์

Apps Script

ฟังก์ชันนี้จะค้นหาวิดีโอที่เกี่ยวข้องกับคีย์เวิร์ด "สุนัข" ระบบจะบันทึกรหัสวิดีโอและชื่อของผลการค้นหาลงในบันทึกของ Apps Script

โปรดทราบว่าตัวอย่างนี้จำกัดผลลัพธ์ไว้ที่ 25 รายการ หากต้องการแสดงผลลัพธ์เพิ่มเติม ให้ส่งพารามิเตอร์เพิ่มเติมตามที่ระบุไว้ที่นี่ https://developers.google.com/youtube/data/reference/rest/v3/search/list 
function searchByKeyword() {
  var results = YouTube.Search.list('id,snippet', {q: 'dogs', maxResults: 25});

  for(var i in results.items) {
    var item = results.items[i];
    Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title);
  }
}

Go

ตัวอย่างโค้ดนี้เรียกใช้เมธอด search.list ของ API เพื่อดึงผลการค้นหาที่เชื่อมโยง กับคีย์เวิร์ดหนึ่งๆ

ตัวอย่างนี้ใช้ไลบรารีของไคลเอ็นต์ Go

package main

import (
	"flag"
	"fmt"
	"log"
	"net/http"

	"google.golang.org/api/googleapi/transport"
	"google.golang.org/api/youtube/v3"
)

var (
	query      = flag.String("query", "Google", "Search term")
	maxResults = flag.Int64("max-results", 25, "Max YouTube results")
)

const developerKey = "YOUR DEVELOPER KEY"

func main() {
	flag.Parse()

	client := &http.Client{
		Transport: &transport.APIKey{Key: developerKey},
	}

	service, err := youtube.New(client)
	if err != nil {
		log.Fatalf("Error creating new YouTube client: %v", err)
	}

	// Make the API call to YouTube.
	call := service.Search.List("id,snippet").
		Q(*query).
		MaxResults(*maxResults)
	response, err := call.Do()
	handleError(err, "")

	// Group video, channel, and playlist results in separate lists.
	videos := make(map[string]string)
	channels := make(map[string]string)
	playlists := make(map[string]string)

	// Iterate through each item and add it to the correct list.
	for _, item := range response.Items {
		switch item.Id.Kind {
		case "youtube#video":
			videos[item.Id.VideoId] = item.Snippet.Title
		case "youtube#channel":
			channels[item.Id.ChannelId] = item.Snippet.Title
		case "youtube#playlist":
			playlists[item.Id.PlaylistId] = item.Snippet.Title
		}
	}

	printIDs("Videos", videos)
	printIDs("Channels", channels)
	printIDs("Playlists", playlists)
}

// Print the ID and title of each result in a list as well as a name that
// identifies the list. For example, print the word section name "Videos"
// above a list of video search results, followed by the video ID and title
// of each matching video.
func printIDs(sectionName string, matches map[string]string) {
	fmt.Printf("%v:\n", sectionName)
	for id, title := range matches {
		fmt.Printf("[%v] %v\n", id, title)
	}
	fmt.Printf("\n\n")
}

.NET

ตัวอย่างโค้ดต่อไปนี้เรียกใช้เมธอด search.list ของ API เพื่อดึงผลการค้นหาที่เชื่อมโยงกับคีย์เวิร์ดหนึ่งๆ

ตัวอย่างนี้ใช้ไลบรารีของไคลเอ็นต์ .NET

using System;
using System.Collections.Generic;
using System.IO;
using System.Reflection;
using System.Threading;
using System.Threading.Tasks;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.Upload;
using Google.Apis.Util.Store;
using Google.Apis.YouTube.v3;
using Google.Apis.YouTube.v3.Data;

namespace Google.Apis.YouTube.Samples
{
  /// <summary>
  /// YouTube Data API v3 sample: search by keyword.
  /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher.
  /// See https://developers.google.com/api-client-library/dotnet/get_started
  ///
  /// Set ApiKey to the API key value from the APIs & auth > Registered apps tab of
  ///   https://cloud.google.com/console
  /// Please ensure that you have enabled the YouTube Data API for your project.
  /// </summary>
  internal class Search
  {
    [STAThread]
    static void Main(string[] args)
    {
      Console.WriteLine("YouTube Data API: Search");
      Console.WriteLine("========================");

      try
      {
        new Search().Run().Wait();
      }
      catch (AggregateException ex)
      {
        foreach (var e in ex.InnerExceptions)
        {
          Console.WriteLine("Error: " + e.Message);
        }
      }

      Console.WriteLine("Press any key to continue...");
      Console.ReadKey();
    }

    private async Task Run()
    {
      var youtubeService = new YouTubeService(new BaseClientService.Initializer()
      {
        ApiKey = "REPLACE_ME",
        ApplicationName = this.GetType().ToString()
      });

      var searchListRequest = youtubeService.Search.List("snippet");
      searchListRequest.Q = "Google"; // Replace with your search term.
      searchListRequest.MaxResults = 50;

      // Call the search.list method to retrieve results matching the specified query term.
      var searchListResponse = await searchListRequest.ExecuteAsync();

      List<string> videos = new List<string>();
      List<string> channels = new List<string>();
      List<string> playlists = new List<string>();

      // Add each result to the appropriate list, and then display the lists of
      // matching videos, channels, and playlists.
      foreach (var searchResult in searchListResponse.Items)
      {
        switch (searchResult.Id.Kind)
        {
          case "youtube#video":
            videos.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.VideoId));
            break;

          case "youtube#channel":
            channels.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.ChannelId));
            break;

          case "youtube#playlist":
            playlists.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.PlaylistId));
            break;
        }
      }

      Console.WriteLine(String.Format("Videos:\n{0}\n", string.Join("\n", videos)));
      Console.WriteLine(String.Format("Channels:\n{0}\n", string.Join("\n", channels)));
      Console.WriteLine(String.Format("Playlists:\n{0}\n", string.Join("\n", playlists)));
    }
  }
}

Ruby

ตัวอย่างนี้เรียกใช้เมธอด search.list ของ API เพื่อดึงผลการค้นหาที่เชื่อมโยงกับคีย์เวิร์ดหนึ่งๆ

ตัวอย่างนี้ใช้ไลบรารีของไคลเอ็นต์ Ruby

#!/usr/bin/ruby

require 'rubygems'
gem 'google-api-client', '>0.7'
require 'google/api_client'
require 'trollop'

# Set DEVELOPER_KEY to the API key value from the APIs & auth > Credentials
# tab of
# {{ Google Cloud Console }} <{{ https://cloud.google.com/console }}>
# Please ensure that you have enabled the YouTube Data API for your project.
DEVELOPER_KEY = 'REPLACE_ME'
YOUTUBE_API_SERVICE_NAME = 'youtube'
YOUTUBE_API_VERSION = 'v3'

def get_service
  client = Google::APIClient.new(
    :key => DEVELOPER_KEY,
    :authorization => nil,
    :application_name => $PROGRAM_NAME,
    :application_version => '1.0.0'
  )
  youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION)

  return client, youtube
end

def main
  opts = Trollop::options do
    opt :q, 'Search term', :type => String, :default => 'Google'
    opt :max_results, 'Max results', :type => :int, :default => 25
  end

  client, youtube = get_service

  begin
    # Call the search.list method to retrieve results matching the specified
    # query term.
    search_response = client.execute!(
      :api_method => youtube.search.list,
      :parameters => {
        :part => 'snippet',
        :q => opts[:q],
        :maxResults => opts[:max_results]
      }
    )

    videos = []
    channels = []
    playlists = []

    # Add each result to the appropriate list, and then display the lists of
    # matching videos, channels, and playlists.
    search_response.data.items.each do |search_result|
      case search_result.id.kind
        when 'youtube#video'
          videos << "#{search_result.snippet.title} (#{search_result.id.videoId})"
        when 'youtube#channel'
          channels << "#{search_result.snippet.title} (#{search_result.id.channelId})"
        when 'youtube#playlist'
          playlists << "#{search_result.snippet.title} (#{search_result.id.playlistId})"
      end
    end

    puts "Videos:\n", videos, "\n"
    puts "Channels:\n", channels, "\n"
    puts "Playlists:\n", playlists, "\n"
  rescue Google::APIClient::TransmissionError => e
    puts e.result.body
  end
end

main

ข้อผิดพลาด

ตารางต่อไปนี้ระบุข้อความแสดงข้อผิดพลาดที่ API อาจแสดงผลเพื่อตอบสนองต่อการเรียกใช้เมธอดนี้ โปรดดูรายละเอียดเพิ่มเติมในเอกสารประกอบข้อความแสดงข้อผิดพลาด

ประเภทข้อผิดพลาด รายละเอียดข้อผิดพลาด คำอธิบาย
badRequest (400) invalidChannelId พารามิเตอร์ channelId ระบุรหัสช่องที่ไม่ถูกต้อง
badRequest (400) invalidLocation ค่าพารามิเตอร์ location และ/หรือ locationRadius มีรูปแบบไม่ถูกต้อง
badRequest (400) invalidRelevanceLanguage ค่าพารามิเตอร์ relevanceLanguage มีรูปแบบไม่ถูกต้อง
badRequest (400) invalidSearchFilter คำขอมีชุดค่าผสมของตัวกรองการค้นหาและ/หรือข้อจำกัดที่ไม่ถูกต้อง โปรดทราบว่าคุณต้องตั้งค่าพารามิเตอร์ type เป็น video หากตั้งค่าพารามิเตอร์ forContentOwner หรือ forMine เป็น true คุณต้องตั้งค่าพารามิเตอร์ type เป็น video ด้วย หากตั้งค่าสำหรับพารามิเตอร์ eventType, videoCaption, videoCategoryId, videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoSyndicated หรือ videoType

ลองใช้งาน

ใช้ APIs Explorer เพื่อเรียก API นี้และดูคำขอ API และการตอบกลับ