증상: 소유자로 등록된 사이트인데 API 가 403 을 내고, 노출이 있는데 검색어 조회가 비어 오고, 같은 조건의 노출 숫자가 569 와 29 로 달랐습니다.
원인: 속성 주소 형식이 두 가지인데 하나로만 조립했고, 검색어 차원은 아주 적은 검색어를 빼고 주며, 검색어 차원 값을 페이지 값처럼 읽었습니다.
해결:
sites().list() 로 실제 siteUrl 을 받아 쓰고, 실패는 예외나 오류 응답으로만 판정하고, 숫자를 쓰기 전에 무엇을 세는지(차원)를 확인합니다.네 가지를 한 표로
| 본 것 | 얼핏 보이는 것 | 실제 원인 |
|---|---|---|
| sites 나 searchAnalytics 조회가 403 | 서비스 계정에 권한이 없다 | 속성 주소 형식이 틀렸다 |
| 노출이 있는 기간인데 검색어 결과가 0줄 | 조회가 실패했다 | 적은 검색어는 이름 없이 빠진다 |
| 1에서 5위 노출 569 에 클릭 0 | 순위는 높은데 아무도 안 누른다 | 검색어 차원 합이었다. 페이지 기준은 29 |
| DNS 자동 인증에서 "TXT 토큰을 못 찾음" | TXT 레코드가 안 들어갔다 | URL 접두어 속성은 정확한 호스트를 요구한다 |
네 가지 모두 API 가 틀린 값을 준 것이 아니었습니다. 받은 값을 읽는 쪽이 틀렸습니다. 하나씩 적습니다.
403 이 났는데 권한 문제가 아니었다
서치콘솔 속성에는 두 유형이 있습니다. API 에서 쓰는 주소 모양도 다릅니다.
| 속성 유형 | API 의 siteUrl |
|---|---|
| 도메인 속성 | sc-domain:example.com |
| URL 접두어 속성 | https://example.com/ |
같은 계정 안에 두 유형이 섞여 있었는데, 코드는 'sc-domain:' + domain 으로만 주소를 만들었습니다. URL 접두어로 등록된 사이트는 이 주소로 부르면 403 이 납니다. 이것을 "서비스 계정에 권한이 없다"로 읽고 소유자를 다시 추가하라는 숙제를 만들 뻔했습니다. 등록 기록이 맞았고, 틀린 것은 제 조회 방식이었습니다.
고친 방법: 주소를 조립하지 않는다
도메인 이름으로 주소를 만들지 말고, 먼저 등록 목록을 받아 거기 적힌 문자열을 그대로 씁니다.
ents = svc.sites().list().execute().get("siteEntry", [])
for e in ents:
print(e["siteUrl"], e.get("permissionLevel"))
이 출력으로 도메인과 siteUrl 을 짝지은 표를 코드에 박아 두면 다시 틀리지 않습니다. 403 을 보면 권한부터 의심하기 전에 이 목록을 눈으로 확인합니다.
빈 결과가 실패가 아니었다
날짜별로 검색어와 페이지 표를 과거로 거슬러 받는 배치 작업을 만들었습니다. 이때 "날짜 차원으로는 노출이 있는데 검색어 차원 결과가 비었으면 조회 실패로 보고 멈춘다"는 규칙을 넣었습니다.
작업은 받다가 중간에 멈췄습니다. 4월 첫 구간에서 멈추기도 하고 6월 구간에서 멈추기도 했습니다. 멈춘 구간은 노출이 1에서 29건 정도로 적은 때였습니다.
검색어 차원(query, query 와 page 조합)으로 조회하면 검색이 아주 적은 검색어는 이름 없이 빠집니다. 그래서 노출이 조금 있어도 결과는 정상적으로 0줄일 수 있습니다. 검색어 표의 합계가 화면의 전체 노출보다 작은 이유도 같습니다.
고친 방법: 실패는 오류로만 판정한다
결과 줄 수나 다른 차원 합계와의 차이로 실패를 짐작하지 않게 바꿨습니다. API 호출이 예외를 던지거나 오류 응답을 줄 때만 실패로 세고, 그 수가 늘었을 때만 멈춥니다.
fails = 0
try:
rows = svc.searchanalytics().query(siteUrl=site, body=body).execute().get("rows", [])
except HttpError as e:
fails += 1 # 이것만 실패
rows = None
# rows == [] 는 실패가 아니다. 적은 검색어가 빠졌을 수 있다
569 와 29: 같은 조건, 다른 차원
"1에서 5위에 노출 569, 클릭 0" 이라는 숫자를 근거로 판단한 적이 있습니다. 순위는 높은데 아무도 누르지 않는다는 이야기가 됩니다. 그런데 같은 조건을 페이지 기준으로 다시 보니 노출은 29 였습니다.
569 는 검색어 차원 값이었습니다. 한 페이지가 여러 검색어로 뜨면 검색어마다 그 페이지 노출이 따로 잡히고, 이것을 다 더하면 페이지 기준보다 훨씬 커집니다. 검색어 차원 값을 페이지 값처럼 인용한 것이 잘못이었습니다.
그 뒤로는 숫자를 쓰기 전에 "이 숫자가 무엇을 세는가"를 먼저 적습니다. 차원을 바꾸면 이름이 같은 숫자도 달라집니다.
덤: URL 접두어 속성과 DNS 자동 인증
URL 접두어 속성을 Cloudflare 의 DNS 자동 통합으로 인증하려 하니 "TXT 토큰을 못 찾음"이 떴습니다. 자동 통합은 TXT 레코드를 도메인 루트(example.com)에 넣는데, URL 접두어 속성은 정확한 호스트(예: blog.example.com)의 TXT 를 요구합니다.
URL 접두어 속성은 HTML 파일이나 메타 태그로 인증하는 편이 맞았습니다. DNS 자동 인증은 도메인 속성에 맞는 방식입니다.
확인한 환경
| 항목 | 값 |
|---|---|
| API | Search Console API (sites, searchanalytics), 파이썬 google-api-python-client |
| 인증 | 서비스 계정 |
| 속성 유형 확인 | 2026년 8월 22일 |
| 빈 결과 규칙 수정 | 2026년 9월 16일 |
이어 볼 글
사이트맵이 "성공"인데 실제로는 안 읽히는 문제는 서치콘솔 사이트맵이 성공인데 안 읽힐 때에, URL 검사 API 가 unknown 을 낼 때 확인할 것은 URL 검사 API 가 unknown 을 낼 때에 적었습니다. API 인증이 일주일마다 끊긴다면 구글 OAuth invalid_grant 7일 문제를 보세요.
API 를 파이썬으로 부르다 403 과 error code 1010 이 함께 온다면 파이썬 urllib 403 error code 1010을 먼저 보세요.
같은 사이트를 다른 검색 포털에도 등록하는 순서는 다음 웹마스터도구에 워드프레스 사이트 등록하는 법에 적었습니다.
이 글의 내용은 2026년 10월 17일에 마지막으로 확인했습니다. 틀린 곳을 발견하시면 연락처로 알려 주세요.