Search Analytics: query

ต้องมีการให้สิทธิ์

ค้นหาข้อมูลการเข้าชมจากการค้นหาด้วยตัวกรองและพารามิเตอร์ที่กำหนด วิธีนี้จะแสดงแถวเป็น 0 แถวขึ้นไปซึ่งจัดกลุ่มตามคีย์แถว (มิติข้อมูล) ที่คุณกำหนด คุณต้องกำหนดช่วงวันที่อย่างน้อยหนึ่งวัน

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

ผลลัพธ์จะจัดเรียงตามจำนวนคลิกจากมากไปน้อย หากแถว 2 แถวมีจำนวนคลิกเท่ากัน ระบบจะจัดเรียงอย่างไร

ดูตัวอย่าง Python สำหรับการเรียกเมธอดนี้

API นี้มีข้อจำกัดภายในของ Search Console และไม่รับประกันว่าแถวข้อมูลทั้งหมดจะแสดงแต่แถวบนสุด

ดูขีดจำกัดจำนวนข้อมูลที่มี

ตัวอย่าง JSON POST: 
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 [ไม่บังคับ] มีมิติข้อมูลเป็นศูนย์รายการขึ้นไปสำหรับจัดกลุ่มผลการค้นหาผลลัพธ์จะได้รับการจัดกลุ่มตามลำดับที่คุณระบุในมิติข้อมูลเหล่านี้คุณสามารถใช้ชื่อมิติข้อมูลใดก็ได้ทั้งใน dimensionFilterGroups[].filters[].dimension และ "วันที่"ค่ามิติข้อมูลการจัดกลุ่มจะรวมเข้าด้วยกันเพื่อสร้างคีย์ที่ไม่ซ้ำกันสำหรับแถวผลลัพธ์แต่ละแถว หากไม่ได้ระบุมิติข้อมูล ค่าทั้งหมดจะรวมเป็นแถวเดียว ไม่มีการจำกัดจำนวนมิติข้อมูลที่คุณสามารถจัดกลุ่มได้ แต่คุณไม่สามารถจัดกลุ่มตามมิติข้อมูลเดียวกัน 2 ครั้งได้ เช่น [ประเทศ, อุปกรณ์]
searchType string เลิกใช้งานแล้ว ให้ใช้ type แทน
type string [ไม่บังคับ] กรองผลลัพธ์เป็นประเภทต่อไปนี้
  • "discover": ผลการค้นหาใน Discover
  • "googleNews": ผลการค้นหาจาก news.google.com และแอป Google News ใน Android และ iOS ไม่รวมผลการค้นหาจากแท็บ "ข่าวสาร" ใน Google Search
  • "news": ผลการค้นหาจากแท็บ "ข่าวสาร" ใน Google Search
  • "image": ผลการค้นหาจากแท็บ "รูปภาพ" ใน Google Search
  • "video": ผลการค้นหาวิดีโอ
  • "web": [ค่าเริ่มต้น] กรองผลลัพธ์เป็นแท็บแบบรวม ("ทั้งหมด") ใน Google Search ไม่รวมผลการค้นหาของ Discover หรือ Google News
dimensionFilterGroups[] list [ไม่บังคับ] กลุ่มตัวกรองตั้งแต่ 0 กลุ่มขึ้นไปเพื่อใช้กับค่าการจัดกลุ่มมิติข้อมูล กลุ่มตัวกรองทั้งหมดต้องตรงกันเพื่อให้ระบบแสดงแถวในคำตอบ ภายในกลุ่มตัวกรองกลุ่มเดียว คุณสามารถระบุได้ว่าตัวกรองทั้งหมดต้องตรงกัน หรือต้องตรงกันอย่างน้อย 1 รายการ
dimensionFilterGroups[].groupType string ตัวกรองทั้งหมดในกลุ่มนี้ต้องแสดงผลเป็น "จริง" ("and") หรือจะแสดงผลเป็น "จริง" อย่างน้อย 1 รายการ (ยังไม่รองรับ)

ค่าที่ยอมรับได้ มีดังนี้
  • "and": ตัวกรองทั้งหมดในกลุ่มต้องแสดงค่า "จริง" ของกลุ่มตัวกรองต้องเป็น "จริง"
dimensionFilterGroups[].filters[] list [ไม่บังคับ] มีตัวกรองอย่างน้อย 0 รายการเพื่อทดสอบกับแถว ตัวกรองแต่ละรายการประกอบด้วยชื่อมิติข้อมูล โอเปอเรเตอร์ และค่า ความยาวสูงสุด 4,096 อักขระ ตัวอย่าง: 
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string มิติข้อมูลที่ใช้กับตัวกรองนี้ คุณสามารถกรองตามมิติข้อมูลใดก็ได้ที่แสดงที่นี่ แม้ว่าจะไม่ได้จัดกลุ่มตามมิติข้อมูลนั้นก็ตาม

ค่าที่ยอมรับได้ มีดังนี้
  • "country": กรองตามประเทศที่ระบุ ซึ่งระบุด้วยรหัสประเทศ 3 ตัวอักษร (ISO 3166-1 alpha-3)
  • "device": กรองผลการค้นหาตามประเภทอุปกรณ์ที่ระบุ ค่าที่รองรับ:
    • เดสก์ท็อป
    • อุปกรณ์เคลื่อนที่
    • แท็บเล็ต
  • "page": กรองตามสตริง URI ที่ระบุ
  • "query": กรองตามสตริงการค้นหาที่ระบุ
  • "searchAppearance": กรองตามฟีเจอร์ผลการค้นหาที่เจาะจง หากต้องการดูรายการค่าที่ใช้ได้ ให้เรียกใช้การค้นหาที่จัดกลุ่มตาม "searchAppearance"
dimensionFilterGroups[].filters[].operator string [ไม่บังคับ] วิธีที่ค่าที่ระบุต้องตรงกับ (หรือไม่ตรงกัน) กับค่ามิติข้อมูลสำหรับแถว

ค่าที่ยอมรับได้ มีดังนี้
  • "contains": ค่าแถวต้องมีเท่ากับหรือเท่ากับนิพจน์ (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่)
  • "equals": [ค่าเริ่มต้น] นิพจน์ต้องเท่ากับค่าแถวทุกประการ (คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่สำหรับมิติข้อมูลของหน้าเว็บและคำค้นหา)
  • "notContains": ค่าแถวต้องไม่มีนิพจน์เป็นสตริงย่อยหรือตรงกันทั้งหมด (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่)
  • "notEquals": นิพจน์ต้องไม่เท่ากับค่าแถวทุกประการ (คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่สำหรับมิติข้อมูลของหน้าเว็บและคำค้นหา)
  • "includingRegex": นิพจน์ทั่วไป ไวยากรณ์ RE2 ที่ต้องตรงกัน
  • "excludingRegex": นิพจน์ทั่วไป รูปแบบคำสั่ง RE2 ที่ต้องไม่ตรงกัน
dimensionFilterGroups[].filters[].expression string ค่าของตัวกรองที่จะจับคู่หรือยกเว้นโดยขึ้นอยู่กับโอเปอเรเตอร์
aggregationType string

[ไม่บังคับ] วิธีรวบรวมข้อมูล หากรวบรวมตามพร็อพเพอร์ตี้ ระบบจะรวมข้อมูลทั้งหมดของพร็อพเพอร์ตี้เดียวกัน หากรวมตามหน้าเว็บ ข้อมูลทั้งหมดจะรวบรวมโดย Canonical URI หากกรองหรือจัดกลุ่มตามหน้า ให้เลือกอัตโนมัติ มิเช่นนั้น คุณจะรวมตามพร็อพเพอร์ตี้หรือตามหน้าเว็บก็ได้ ทั้งนี้ขึ้นอยู่กับวิธีที่ต้องการคํานวณข้อมูล โปรดดูเอกสารประกอบความช่วยเหลือเพื่อดูวิธีคํานวณข้อมูลตามเว็บไซต์เทียบกับตามหน้าเว็บแตกต่างกัน

หมายเหตุ: หากจัดกลุ่มหรือกรองตามหน้า คุณจะรวมตามพร็อพเพอร์ตี้ไม่ได้

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

ค่าที่ยอมรับได้ มีดังนี้
  • "auto": [ค่าเริ่มต้น] ให้บริการเลือกประเภทการรวมที่เหมาะสม
  • "byNewsShowcasePanel": รวมค่าตามแผง News Showcase ต้องใช้ร่วมกับตัวกรอง NEWS_SHOWCASE searchAppearance และ type=discover หรือ type=googleNews หากจัดกลุ่มตามหน้า กรองตามหน้า หรือกรองตาม searchAppearance อื่น คุณจะรวมข้อมูลตาม byNewsShowcasePanel ไม่ได้
  • "byPage": รวมค่าตาม URI
  • "byProperty": รวมค่าตามพร็อพเพอร์ตี้ ไม่รองรับ type=discover หรือ type=googleNews
rowLimit integer [ไม่บังคับ ช่วงที่ใช้ได้คือ 1–25,000 ค่าเริ่มต้นคือ 1,000] จำนวนแถวสูงสุดที่จะแสดงผล หากต้องการเลื่อนดูผลลัพธ์ ให้ใช้ออฟเซ็ต startRow
startRow integer [ไม่บังคับ ค่าเริ่มต้นคือ 0] ดัชนีแบบ 0 ของแถวแรกในคำตอบ ต้องเป็นตัวเลขที่ไม่เป็นลบ หาก startRow เกินจำนวนผลลัพธ์สำหรับการค้นหาดังกล่าว การตอบกลับจะเป็นการตอบกลับที่สำเร็จโดยมี 0 แถว
dataState string [ไม่บังคับ] หากเป็น "ทั้งหมด" (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) ข้อมูลจะมีข้อมูลที่ใหม่ หาก "สุดท้าย" (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) หรือหากละเว้นพารามิเตอร์นี้ ข้อมูลที่ส่งคืนจะรวมเฉพาะข้อมูลสรุป

คำตอบ

ผลลัพธ์จะได้รับการจัดกลุ่มตามมิติข้อมูลที่ระบุไว้ในคำขอ ค่าทั้งหมดที่มีค่ามิติข้อมูลชุดเดียวกันจะจัดกลุ่มไว้ในแถวเดียว ตัวอย่างเช่น หากคุณจัดกลุ่มตามมิติข้อมูลประเทศ ระบบจะจัดกลุ่มผลลัพธ์ทั้งหมดสำหรับ "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 วิธีรวบรวมผลลัพธ์โปรดดูเอกสารความช่วยเหลือเพื่อดูวิธีการคำนวณข้อมูลที่แตกต่างกันตามเว็บไซต์เทียบกับตามหน้าเว็บ

ค่าที่ยอมรับได้ มีดังนี้
  • "auto"
  • "byPage": รวบรวมผลลัพธ์ตามหน้าเว็บ
  • "byProperty": รวบรวมผลลัพธ์ตามพร็อพเพอร์ตี้

ลองใช้เลย

ใช้ API Explorer ด้านล่างเพื่อเรียกใช้เมธอดนี้กับข้อมูลแบบสดและดูการตอบกลับ