Search Analytics: query

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

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

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

ผลลัพธ์จะจัดเรียงตามจำนวนคลิกจากมากไปน้อย หาก 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
}
ชื่อพร็อพเพอร์ตี้ ค่า คำอธิบาย หมายเหตุ
startDate string [ต้องระบุ] วันที่เริ่มต้นของช่วงวันที่ที่ขอ ในรูปแบบ ปปปป-ดด-วว ตามเวลา PT (UTC - 7:00/8:00) ต้องน้อยกว่าหรือเท่ากับวันที่สิ้นสุด ค่านี้รวมอยู่ในช่วง
endDate string [ต้องระบุ] วันที่สิ้นสุดของช่วงวันที่ที่ขอ ในรูปแบบ ปปปป-ดด-วว ตามเวลา PT (UTC - 7:00/8:00) ต้องมากกว่าหรือเท่ากับวันที่เริ่มต้น ค่านี้รวมอยู่ในช่วง
dimensions[] list [ไม่บังคับ] มิติข้อมูล 0 รายการขึ้นไปที่จะใช้จัดกลุ่มผลลัพธ์ ระบบจะจัดกลุ่มผลลัพธ์ตามลำดับที่คุณระบุมิติข้อมูลเหล่านี้คุณสามารถใช้ชื่อมิติข้อมูลใดก็ได้ใน dimensionFilterGroups[].filters[].dimension รวมถึง "date" และ "hour" ระบบจะรวมค่ามิติข้อมูลการจัดกลุ่มเพื่อสร้างคีย์ที่ไม่ซ้ำกันสำหรับแต่ละแถวผลลัพธ์ หากไม่ได้ระบุมิติข้อมูล ระบบจะรวมค่าทั้งหมดไว้ในแถวเดียว คุณจัดกลุ่มตามมิติข้อมูลได้ไม่จำกัดจำนวน แต่จะจัดกลุ่มตามมิติข้อมูลเดียวกัน 2 ครั้งไม่ได้ ตัวอย่าง: [country, device]
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 รายการขึ้นไปที่จะทดสอบกับแถว ตัวกรองแต่ละรายการประกอบด้วย ชื่อมิติข้อมูล โอเปอเรเตอร์ และค่า ความยาวสูงสุด 4096 อักขระ ตัวอย่าง 
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string มิติข้อมูลที่ตัวกรองนี้ใช้ คุณสามารถกรองตามมิติข้อมูลใดก็ได้ที่แสดงที่นี่ แม้ว่าจะไม่ได้จัดกลุ่มตามมิติข้อมูลนั้นก็ตาม

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

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

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

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

หากระบุค่าอื่นที่ไม่ใช่ "อัตโนมัติ" ประเภทการรวมในผลลัพธ์จะตรงกับประเภทที่ขอ หรือ หากคุณขอประเภทที่ไม่ถูกต้อง คุณจะได้รับข้อผิดพลาด 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 [ไม่บังคับ] หากเป็น "all" (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) ข้อมูลจะรวม ข้อมูลล่าสุด. หากเป็น "final" (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) หรือหากละเว้นพารามิเตอร์นี้ ข้อมูลที่แสดงผลจะรวมเฉพาะข้อมูลที่สรุปแล้ว หากเป็น "hourly_all" (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) ข้อมูลจะรวมรายละเอียดรายชั่วโมง ซึ่งจะบ่งชี้ว่าข้อมูลรายชั่วโมงมีข้อมูลบางส่วนและควรใช้เมื่อจัดกลุ่มตามมิติข้อมูล HOUR API

คำตอบ

ระบบจะจัดกลุ่มผลลัพธ์ตามมิติข้อมูลที่ระบุในคำขอ ค่าทั้งหมดที่มีชุดค่ามิติข้อมูลเดียวกันจะจัดกลุ่มไว้ในแถวเดียว ตัวอย่างเช่น หากคุณจัดกลุ่มตามมิติข้อมูลประเทศ ระบบจะจัดกลุ่มผลลัพธ์ทั้งหมดสำหรับ "usa" ไว้ด้วยกัน ผลลัพธ์ทั้งหมดสำหรับ "mdv" ไว้ด้วยกัน และอื่นๆ หากคุณจัดกลุ่มตามประเทศและอุปกรณ์ ระบบจะจัดกลุ่มผลลัพธ์ทั้งหมดสำหรับ "usa, tablet" ผลลัพธ์ทั้งหมดสำหรับ "usa, mobile" และอื่นๆ โปรดดูเอกสารประกอบรายงานการวิเคราะห์การค้นหาเพื่อดูรายละเอียดเกี่ยวกับวิธีคำนวณการคลิก การแสดงผล และอื่นๆ รวมถึงความหมายของข้อมูลเหล่านั้น

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

โปรดดูพร็อพเพอร์ตี้ rowLimit ในคำขอเพื่อดูจำนวนค่าสูงสุดที่แสดงผลได้

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
ชื่อพร็อพเพอร์ตี้ ค่า คำอธิบาย หมายเหตุ
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": ระบบรวมผลลัพธ์ตามพร็อพเพอร์ตี้
metadata object

ออบเจ็กต์ที่อาจแสดงผลพร้อมกับผลการค้นหา ซึ่งให้ข้อมูลบริบทเกี่ยวกับสถานะของข้อมูล

เมื่อคุณขอข้อมูลล่าสุด (โดยใช้ all หรือ hourly_all สำหรับ dataState) แถวบางแถวที่แสดงผลอาจแสดงข้อมูลที่ไม่สมบูรณ์ ซึ่งหมายความว่าระบบยังคงรวบรวมและประมวลผลข้อมูลอยู่ ออบเจ็กต์ข้อมูลเมตานี้ จะช่วยให้คุณระบุเวลาเริ่มต้นและสิ้นสุดที่แน่นอนได้

วันที่และเวลาทั้งหมดที่ระบุในออบเจ็กต์นี้อยู่ในเขตเวลา America/Los_Angeles

ช่องที่เฉพาะเจาะจงซึ่งแสดงผลภายในออบเจ็กต์นี้จะขึ้นอยู่กับวิธีที่คุณจัดกลุ่มข้อมูลใน คำขอ ดังนี้

  • first_incomplete_date (string): วันแรกที่ระบบยังคงรวบรวมและประมวลผลข้อมูล ซึ่งแสดงในรูปแบบ YYYY-MM-DD (รูปแบบวันที่ท้องถิ่นแบบขยาย ISO-8601)

    ระบบจะป้อนข้อมูลในช่องนี้ก็ต่อเมื่อ dataState ของคำขอเป็น all และข้อมูลจัดกลุ่มตาม date รวมถึงช่วงวันที่ที่ขอมีจุดข้อมูลที่ไม่สมบูรณ์

    ค่าทั้งหมดหลังจาก first_incomplete_date อาจยังคงเปลี่ยนแปลงอย่างเห็นได้ชัด

  • first_incomplete_hour (string): ชั่วโมงแรกที่ระบบยังคงรวบรวมและประมวลผลข้อมูล ซึ่งแสดงในรูปแบบ YYYY-MM-DDThh:mm:ss[+|-]hh:mm (รูปแบบวันที่และเวลาแบบออฟเซ็ตแบบขยาย ISO-8601)

    ระบบจะป้อนข้อมูลในช่องนี้ก็ต่อเมื่อ dataState ของคำขอเป็น hourly_all, และข้อมูลจัดกลุ่มตาม hour รวมถึงช่วงวันที่ที่ขอมีจุดข้อมูลที่ไม่สมบูรณ์

    ค่าทั้งหมดหลังจาก first_incomplete_hour อาจยังคงเปลี่ยนแปลงอย่างเห็นได้ชัด

ลองใช้งาน

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