ต้องมีการให้สิทธิ์
ค้นหาข้อมูลการเข้าชมจากการค้นหาด้วยตัวกรองและพารามิเตอร์ที่คุณกำหนด เมธอดจะแสดงแถวอย่างน้อย 0 แถวที่จัดกลุ่มตามคีย์แถว (มิติข้อมูล) ที่คุณกำหนด คุณต้องกำหนดช่วงวันที่อย่างน้อยหนึ่งวัน
เมื่อวันที่เป็นหนึ่งในมิติข้อมูล วันที่ไม่มีข้อมูลจะไม่ปรากฏในรายการผลลัพธ์ หากต้องการทราบว่าวันใดมีข้อมูล ให้ทำการค้นหาโดยไม่ใช้ตัวกรองที่จัดกลุ่มตามวันที่สำหรับช่วงวันที่ที่สนใจ
ผลลัพธ์จะจัดเรียงตามจำนวนคลิกจากมากไปน้อย หาก 2 แถวมีจำนวนคลิกเท่ากัน ระบบจะจัดเรียงตามลำดับ
ดูตัวอย่างของ Python สำหรับการเรียกใช้เมธอดนี้
API อยู่ภายใต้ข้อจำกัดภายในของ Search Console และไม่รับประกันว่าจะแสดงแถวข้อมูลทั้งหมด แต่จะแสดงแถวบนสุด
ดูขีดจำกัดของปริมาณข้อมูลที่ใช้ได้
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY} { "startDate": "2015-04-01", "endDate": "2015-05-01", "dimensions": ["country","device"] }
ส่งคำขอ
คำขอ HTTP
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
พารามิเตอร์
ชื่อพารามิเตอร์ | ค่า | คำอธิบาย |
---|---|---|
พารามิเตอร์เส้นทาง | ||
siteUrl |
string |
URL ของพร็อพเพอร์ตี้ตามที่ระบุไว้ใน Search Console เช่น
http://www.example.com/ (สำหรับพร็อพเพอร์ตี้คำนำหน้า URL) หรือ sc-domain:example.com (สำหรับพร็อพเพอร์ตี้โดเมน)
|
การให้สิทธิ์
คำขอนี้ต้องได้รับสิทธิ์อย่างน้อย 1 ขอบเขตต่อไปนี้ (อ่านเพิ่มเติมเกี่ยวกับการตรวจสอบสิทธิ์และการให้สิทธิ์)
ขอบเขต |
---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
เนื้อหาของคำขอ
ในเนื้อหาคำขอ ให้ข้อมูลตามโครงสร้างต่อไปนี้
{ "startDate": string, "endDate": string, "dimensions": [ string ], "type": string, "dimensionFilterGroups": [ { "groupType": string, "filters": [ { "dimension": string, "operator": string, "expression": string } ] } ], "aggregationType": string, "rowLimit": integer, "startRow": integer }
ชื่อพร็อพเพอร์ตี้ | ค่า | คำอธิบาย | Notes |
---|---|---|---|
startDate |
string |
[ต้องระบุ] วันที่เริ่มต้นของช่วงวันที่ที่ขอในรูปแบบ YYYY-MM-DD ในเวลา PT (UTC - 7:00/8:00) ต้องน้อยกว่าหรือเท่ากับวันที่สิ้นสุด ค่านี้จะรวมอยู่ในช่วง | |
endDate |
string |
[ต้องระบุ] วันที่สิ้นสุดของช่วงวันที่ที่ขอในรูปแบบ YYYY-MM-DD ตามเวลา PT (UTC - 7:00/8:00) ต้องมากกว่าหรือเท่ากับวันที่เริ่มต้น ค่านี้จะรวมอยู่ในช่วง | |
dimensions[] |
list |
[ไม่บังคับ] ใช้มิติข้อมูลตั้งแต่ 0 รายการขึ้นไปในการจัดกลุ่มผลลัพธ์ผลลัพธ์จะถูกจัดกลุ่มตามลำดับที่คุณระบุมิติข้อมูลเหล่านี้คุณสามารถใช้ชื่อมิติข้อมูลใดก็ได้ใน dimensionFilterGroups[].filters[].dimension รวมถึง "วันที่"ระบบจะรวมค่ามิติข้อมูลการจัดกลุ่มเพื่อสร้างคีย์ที่ไม่ซ้ำกันสำหรับแถวผลลัพธ์แต่ละแถว หากไม่ได้ระบุมิติข้อมูลไว้ ระบบจะรวมค่าทั้งหมดไว้ในแถวเดียว คุณจัดกลุ่มมิติข้อมูลได้ไม่จำกัดจำนวน แต่จะจัดกลุ่มตามมิติข้อมูลเดียวกัน 2 ครั้งไม่ได้ ตัวอย่าง: [ประเทศ อุปกรณ์] | |
searchType |
string |
เลิกใช้งานแล้ว ใช้ type แทน
|
|
type |
string |
[ไม่บังคับ] กรองผลลัพธ์เป็นประเภทต่อไปนี้
|
|
dimensionFilterGroups[] |
list |
[ไม่บังคับ] กลุ่มตัวกรองอย่างน้อย 0 กลุ่มที่จะใช้กับค่าการจัดกลุ่มมิติข้อมูล กลุ่มตัวกรองทั้งหมดต้องตรงกันเพื่อให้ระบบแสดงแถวในคำตอบ คุณระบุได้ว่าตัวกรองทั้งหมดต้องตรงกันหรืออย่างน้อย 1 รายการในกลุ่มตัวกรองกลุ่มเดียว | |
dimensionFilterGroups[].groupType |
string |
ตัวกรองทั้งหมดในกลุ่มนี้ต้องแสดงค่าเป็น "จริง" ("และ") หรืออย่างน้อย 1 รายการต้องแสดงค่าเป็น "จริง" (ยังไม่รองรับ)
ค่าที่ยอมรับมีดังนี้
|
|
dimensionFilterGroups[].filters[] |
list |
[ไม่บังคับ] ตัวกรองอย่างน้อย 0 รายการที่จะทดสอบกับแถว ตัวกรองแต่ละรายการประกอบด้วยชื่อมิติข้อมูล โอเปอเรเตอร์ และค่า ความยาวสูงสุด 4,096 อักขระ ตัวอย่าง:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
มิติข้อมูลที่ตัวกรองนี้ใช้ คุณสามารถกรองตามมิติข้อมูลที่ระบุไว้ที่นี่ได้ แม้ว่าคุณจะไม่ได้จัดกลุ่มตามมิติข้อมูลนั้นก็ตาม
ค่าที่ยอมรับมีดังนี้
|
|
dimensionFilterGroups[].filters[].operator |
string |
[ไม่บังคับ] วิธีที่ค่าที่ระบุต้องตรงกับ (หรือไม่ตรงกัน) กับค่ามิติข้อมูลสำหรับแถว
ค่าที่ยอมรับมีดังนี้
|
|
dimensionFilterGroups[].filters[].expression |
string |
ค่าสำหรับตัวกรองที่จะจับคู่หรือยกเว้น ทั้งนี้ขึ้นอยู่กับโอเปอเรเตอร์ | |
aggregationType |
string |
[ไม่บังคับ] วิธีรวบรวมข้อมูล หากรวบรวมตามพร็อพเพอร์ตี้ ระบบจะรวบรวมข้อมูลทั้งหมดของพร็อพเพอร์ตี้เดียวกัน หากรวบรวมตามหน้าเว็บ ข้อมูลทั้งหมดจะรวมโดย URI ตามรูปแบบบัญญัติ หากคุณกรองหรือจัดกลุ่มตามหน้า ให้เลือก "อัตโนมัติ" มิเช่นนั้นคุณรวบรวมข้อมูลตามพร็อพเพอร์ตี้หรือตามหน้าเว็บก็ได้ โดยขึ้นอยู่กับวิธีที่คุณต้องการคำนวณข้อมูล โปรดดูเอกสารประกอบเกี่ยวกับความช่วยเหลือเพื่อดูวิธีคำนวณข้อมูลที่แตกต่างกันตามเว็บไซต์เทียบกับตามหน้าเว็บ หมายเหตุ: หากจัดกลุ่มหรือกรองตามหน้า คุณจะรวบรวมข้อมูลตามพร็อพเพอร์ตี้ไม่ได้ หากคุณระบุค่าอื่นที่ไม่ใช่อัตโนมัติ ประเภทการรวมในผลลัพธ์จะตรงกับประเภทที่ขอ หรือหากคุณขอประเภทที่ไม่ถูกต้อง คุณจะได้รับข้อผิดพลาด API จะไม่เปลี่ยนประเภทการรวมหากประเภทที่ขอไม่ถูกต้อง ค่าที่ยอมรับมีดังนี้
|
|
rowLimit |
integer |
[ไม่บังคับ ช่วงที่ใช้ได้คือ 1–25,000 ค่าเริ่มต้นคือ 1,000] จำนวนแถวสูงสุดที่จะแสดง หากต้องการเลื่อนดูผลการค้นหา ให้ใช้ออฟเซ็ต startRow |
|
startRow |
integer |
[ไม่บังคับ ค่าเริ่มต้นคือ 0] ดัชนีแบบศูนย์ของแถวแรกในคำตอบ ต้องเป็นตัวเลขที่ไม่ใช่ค่าลบ หาก startRow มีจำนวนผลการค้นหาเกินขีดจำกัด การตอบกลับจะเป็นคำตอบที่สำเร็จโดยมี 0 แถว |
|
dataState |
string |
[ไม่บังคับ] หากเป็น "ทั้งหมด" (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) ข้อมูลจะรวมข้อมูลใหม่ด้วย หากเป็น "Final" (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) หรือหากละเว้นพารามิเตอร์นี้ ข้อมูลที่แสดงผลจะรวมเฉพาะรายได้สรุปเท่านั้น |
คำตอบ
ผลลัพธ์จะจัดกลุ่มตามมิติข้อมูลที่ระบุไว้ในคำขอ ระบบจะจัดกลุ่มค่าทั้งหมดที่มีชุดค่ามิติข้อมูลเดียวกันเป็นแถวเดียว ตัวอย่างเช่น หากคุณจัดกลุ่มตามมิติข้อมูลประเทศ ผลลัพธ์ทั้งหมดสำหรับ "usa" จะถูกจัดกลุ่มเข้าด้วยกัน ผลลัพธ์ทั้งหมดสำหรับ "mdv" จะถูกจัดกลุ่มเข้าด้วยกัน เป็นต้น หากคุณจัดกลุ่มตามประเทศและอุปกรณ์ ระบบจะจัดกลุ่มผลลัพธ์ทั้งหมดสำหรับ "สหรัฐอเมริกา แท็บเล็ต" และจัดกลุ่มผลลัพธ์ทั้งหมดสำหรับ "สหรัฐอเมริกา, มือถือ" เป็นต้น ดูเอกสารประกอบของรายงานการวิเคราะห์การค้นหา เพื่อดูข้อมูลที่เฉพาะเจาะจงเกี่ยวกับวิธีการคำนวณจำนวนคลิก การแสดงผล และอื่นๆ รวมถึงความหมายของจำนวนคลิก
ผลลัพธ์จะจัดเรียงตามจำนวนคลิกจากมากไปน้อย เว้นแต่คุณจะจัดกลุ่มตามวันที่ ซึ่งในกรณีนี้ผลการค้นหาจะจัดเรียงตามวันที่จากน้อยไปหามาก (เก่าสุดก่อนใหม่สุด ล่าสุด) หากแถว 2 แถวมีลำดับเท่ากัน ลำดับการจัดเรียงจะเป็นแบบใดก็ได้
ดูพร็อพเพอร์ตี้ rowLimit ในคำขอเพื่อดูจำนวนค่าสูงสุดที่แสดงผลได้
{ "rows": [ { "keys": [ string ], "clicks": double, "impressions": double, "ctr": double, "position": double } ], "responseAggregationType": string }
ชื่อพร็อพเพอร์ตี้ | ค่า | คำอธิบาย | Notes |
---|---|---|---|
rows[] |
list |
รายการของแถวที่จัดกลุ่มตามค่าคีย์ตามลำดับที่ระบุในคำค้นหา | |
rows[].keys[] |
list |
รายการค่ามิติข้อมูลสำหรับแถวนั้น ซึ่งจัดกลุ่มตามมิติข้อมูลในคำขอตามลำดับที่ระบุในคำขอ | |
rows[].clicks |
double |
จำนวนคลิกสำหรับแถวนั้นๆ | |
rows[].impressions |
double |
จำนวนการแสดงผลสำหรับแถว | |
rows[].ctr |
double |
อัตราการคลิกผ่าน (CTR) ของแถว มีค่าตั้งแต่ 0 ถึง 1.0 โดยรวม | |
rows[].position |
double |
อันดับเฉลี่ยในผลการค้นหา | |
responseAggregationType |
string |
วิธีรวบรวมผลลัพธ์โปรดดูเอกสารประกอบเกี่ยวกับความช่วยเหลือเพื่อดูวิธีการคำนวณข้อมูลแตกต่างกันในแต่ละเว็บไซต์เมื่อเทียบกับข้อมูลตามหน้าเว็บ
ค่าที่ยอมรับมีดังนี้
|
ลองใช้เลย
ใช้ API Explorer ด้านล่างเพื่อเรียกใช้เมธอดนี้กับข้อมูลแบบเรียลไทม์และดูการตอบสนอง