{"openapi":"3.1.0","info":{"title":"GSC GA4 数据接口","version":"1.2.0"},"servers":[{"url":"https://gscga.fawz-cos.com"}],"paths":{"/api/sites":{"get":{"summary":"Api Sites","description":"列出已经配置的网站及对应 site_id。","operationId":"listSites","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Listsites"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/gsc":{"get":{"summary":"Api Gsc","description":"GSC 报表，view: overview/daily/queries/pages/devices/countries。数据限制详见返回的 notes。","operationId":"getGscReport","security":[{"HTTPBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string","title":"Site Id"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","default":"overview","title":"View"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getgscreport"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ga4":{"get":{"summary":"Api Ga","description":"GA4 报表。browser 可填 Chrome、Safari 等精确名称，空值查询全部浏览器。view: overview/daily/channels/pages/devices/countries/browsers/browser_daily。日期含起止两天，使用 GA4 属性时区。注意 hostName 的会话统计口径。","operationId":"getGa4Report","security":[{"HTTPBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string","title":"Site Id"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","default":"overview","title":"View"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"title":"Limit"}},{"name":"browser","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getga4Report"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ga4/properties":{"get":{"summary":"Api Ga Properties","description":"列出已授权账号可读取的 GA4 属性，不需要配对 GSC 或先保存网站。","operationId":"listGa4Properties","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Listga4Properties"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/ga4/domains":{"get":{"summary":"Api Ga Domains","description":"查询该日期范围内属性实际记录的域名 hostName，核对域名与属性对应关系。","operationId":"getGa4Domains","security":[{"HTTPBearer":[]}],"parameters":[{"name":"property_id","in":"query","required":true,"schema":{"type":"string","title":"Property Id"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getga4Domains"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ga4/query":{"post":{"summary":"Api Ga Query","description":"只读 GA4 自由报表，指定 property_id、hostname、browser 和完整日期范围。dimensions 默认 date（每天），date+browser（每天各浏览器），browser（浏览器汇总），空列表（整体）。metrics 可填任意兼容的 GA4 API 指标，默认用户数、会话数、浏览量、参与会话、参与率、关键事件。不修改 Google 数据，报表存档到自建服务器。","operationId":"queryGa4Report","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GaQuery"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Queryga4Report"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"x-openai-isConsequential":false}},"/api/compare":{"get":{"summary":"Api Compare","description":"比较当前周期与上一等长周期。缺失数据不能当作零。","operationId":"comparePeriods","security":[{"HTTPBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string","title":"Site Id"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Compareperiods"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/history":{"get":{"summary":"Api History","description":"列出已经保存的历史报表。没有获取过的数据不在存档中。","operationId":"listArchives","security":[{"HTTPBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listarchives"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/archive":{"get":{"summary":"Api Archive","description":"按 report_id 读取已存档报表，返回采集时间和日期范围。","operationId":"getArchive","security":[{"HTTPBearer":[]}],"parameters":[{"name":"report_id","in":"query","required":true,"schema":{"type":"integer","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getarchive"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/gsc/properties":{"get":{"summary":"Api Gsc Properties","description":"独立列出授权 GSC 属性，不依赖 GA4。","operationId":"listGscProperties","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Listgscproperties"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/gsc/query":{"post":{"summary":"Api Gsc Query","description":"只返回点击、展现、CTR和平均排名。可组合维度/时间/路径/搜索类型，next_offset继续分页；明细不是完整全集。","operationId":"queryGscReport","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GscQuery"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Querygscreport"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"x-openai-isConsequential":false}},"/api/ga4/fields":{"get":{"summary":"Api Ga Fields","description":"按属性发现维度和指标（含已注册自定义字段）。search可搜索英文名称/说明，先查字段再查询数据。","operationId":"getGa4Fields","security":[{"HTTPBearer":[]}],"parameters":[{"name":"property_id","in":"query","required":true,"schema":{"type":"string","title":"Property Id"}},{"name":"search","in":"query","required":false,"schema":{"type":"string","default":"","title":"Search"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getga4Fields"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ga4/compatibility":{"post":{"summary":"Api Ga Compatibility","description":"验证指定属性维度、指标与附加筛选兼容性；UNKNOWN不能视为已兼容。","operationId":"checkGa4Compatibility","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Compatibility"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Checkga4Compatibility"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"x-openai-isConsequential":false}},"/api/content/mappings":{"get":{"summary":"Api Content Mappings","description":"分页读取管理员确认的GA4属性/域名/路径到稳定文章ID映射。","operationId":"listContentMappings","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listcontentmappings"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/content/query":{"post":{"summary":"Api Content Query","description":"按确认映射查询跨域文章浏览量/事件数，附原始报表证据。用户/会话不相加，跨属性重复事件未去重。","operationId":"queryContentReport","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentQuery"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Querycontentreport"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}],"x-openai-isConsequential":false}},"/api/jobs":{"get":{"summary":"Api Jobs","description":"只读同步/回填任务进度，失败原因和查询条件。","operationId":"listSyncJobs","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listsyncjobs"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/alerts":{"get":{"summary":"Api Alerts","description":"读取采集失败和流量偏离提醒；后台内部提醒，未发送邮件或消息。","operationId":"listAlerts","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"unread","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Unread"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listalerts"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/export":{"get":{"summary":"Api Export","description":"返回Excel下载地址，需要管理员浏览器登录。report_id单页存档；job_id全部已完成任务分页，未完成任务会标记部分结果。","operationId":"getExcelDownload","security":[{"HTTPBearer":[]}],"parameters":[{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Report Id"}},{"name":"job_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getexceldownload"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Compatibility":{"properties":{"property_id":{"type":"string","pattern":"^[0-9]{1,20}$","title":"Property Id"},"dimensions":{"items":{"type":"string"},"type":"array","maxItems":9,"title":"Dimensions"},"metrics":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Metrics"},"filters":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":10},{"type":"null"}],"title":"Filters"}},"type":"object","required":["property_id","metrics"],"title":"Compatibility"},"ContentQuery":{"properties":{"content_id":{"type":"string","maxLength":200,"minLength":1,"title":"Content Id"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"daily":{"type":"boolean","title":"Daily","default":false}},"type":"object","required":["content_id"],"title":"ContentQuery"},"GaQuery":{"properties":{"property_id":{"type":"string","pattern":"^[0-9]{1,20}$","title":"Property Id"},"hostname":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"title":"Hostname"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"browser":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Browser"},"dimensions":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":9},{"type":"null"}],"title":"Dimensions"},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1},{"type":"null"}],"title":"Metrics"},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","default":1000},"offset":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"Offset","default":0},"source":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Source","description":"会话来源包含匹配，如 google/yandex；自然搜索需同时 medium=organic"},"medium":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Medium"},"page":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Page"},"page_match":{"type":"string","enum":["EXACT","BEGINS_WITH","ENDS_WITH","CONTAINS","FULL_REGEXP","PARTIAL_REGEXP"],"title":"Page Match","default":"EXACT"},"filters":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":10},{"type":"null"}],"title":"Filters","description":"AND筛选，每项field/value/match/case_sensitive；先查询属性字段列表"}},"type":"object","required":["property_id"],"title":"GaQuery"},"GscQuery":{"properties":{"property":{"type":"string","maxLength":500,"minLength":1,"title":"Property","description":"从 listGscProperties 获取，sc-domain:域名 或 URL 前缀"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"dimensions":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":6},{"type":"null"}],"title":"Dimensions","description":"date/query/page/country/device/searchAppearance 可组合，[]整体"},"search_type":{"type":"string","enum":["web","image","video","news","discover","googleNews"],"title":"Search Type","default":"web"},"page":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Page","description":"完整URL或/开头路径"},"page_match":{"type":"string","enum":["exact","prefix","contains"],"title":"Page Match","default":"exact"},"filters":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":10},{"type":"null"}],"title":"Filters","description":"AND筛选，dimension/operator/expression"},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","default":1000},"offset":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"Offset","default":0}},"type":"object","required":["property"],"title":"GscQuery"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}