위치와 언어: gl, hl, location, google_domain, device

gl, hl, location의 차이는 무엇인가요?

gl은 어느 국가의 결과를 원하는지 지정합니다. hl은 사용자가 읽는 언어를 지정하며, 이는 인터페이스와 흔히 질문 및 스니펫을 바꿉니다. location는 국가를 도시나 지역으로 좁히며, 검색 쿼리에 로컬 의도가 있는 순간부터 중요해집니다.

세 값은 자유롭게 조합됩니다. 스위스에 있는 프랑스어 사용자는 gl=ch, hl=fr입니다. 베를린에서의 영어 검색은 gl=de, hl=en, location=Berlin, Berlin, Germany입니다. gl과 location의 국가는 같게 유지하세요. 한 국가의 도시에 다른 국가의 gl을 지정하면 실제 방문자가 보는 결과와 다른 결과가 나옵니다.

도시를 어떻게 타겟팅하나요?

장소는 영어로, 가장 작은 단위에서 가장 큰 단위 순으로 작성하세요: City, Region, Country. 예: Austin, Texas, United States, Manchester, England, United Kingdom, Munich, Bavaria, Germany, Lyon, Auvergne-Rhone-Alpes, France. 거리나 우편번호가 아니라 도시 이름을 사용하세요.

응답에서 search_parameters.location을 확인하세요. 적용된 장소가 표시됩니다. 사용할 수 없는 값은 400 invalid_parameter을 반환하고 비용이 들지 않으므로, 장소 목록을 저렴하게 테스트할 수 있습니다.

# The same query from two cities: compare the local packs
for city in "Austin, Texas, United States" "Denver, Colorado, United States"; do
  curl -sG "https://serpcrypto.com/api/v1/search" \
    -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
    --data-urlencode "q=emergency plumber" \
    --data-urlencode "location=$city" \
    -d gl=us -d hl=en -d device=mobile \
    | jq -r --arg city "$city" '.local_results[]? | "\($city)\t\(.position)\t\(.title)"'
done

어떤 Google 도메인을 사용해야 하나요?

보통은 필요 없습니다. google_domain을 생략하면 위 표처럼 gl 국가의 도메인이 API에 사용됩니다. 특정 환경을 재현할 때만 설정하세요. 예를 들어 google.com에 gl=gb을 함께 쓰는 경우입니다.

도메인만으로는 검색 결과의 국가가 정해지지 않습니다. 실제로는 gl와 location가 대부분을 결정하며, 그래서 응답에는 세 가지가 모두 search_parameters에 기록됩니다.

모바일과 데스크톱 검색 결과는 다른가요?

대개 다릅니다. 모바일 페이지는 블록 순서가 달라질 수 있고, 근처 지역 의도를 반영한 결과가 더 많이 나오며, 스니펫이 더 짧게 잘리기도 합니다. 방문자가 주로 휴대폰을 쓴다면 device=mobile를 추적하세요. 전체를 파악하려면 둘 다 추적하고 각 순위와 함께 기기를 저장하세요.

기기마다 별도의 검색이므로 둘 다 추적하면 해당 키워드의 크레딧이 두 배로 듭니다. 검색 100,000회 팩 기준 US$0.56/1K 검색 크레딧에서는 키워드 1,000개를 두 기기에서 30일간 추적할 때 검색 60,000회를 사용합니다.

한 스크립트에서 여러 국가를 어떻게 비교하나요?

마켓 목록을 순회하면서 API가 실제로 적용한 값을 저장하세요. Python 예제는 하나의 검색 쿼리를 각각 도시를 지정해 세 국가로 보내고, 사용된 도메인과 첫 번째 링크를 출력합니다.

import os

import requests

MARKETS = [
    {"gl": "de", "hl": "de", "location": "Munich, Bavaria, Germany"},
    {"gl": "fr", "hl": "fr", "location": "Lyon, Auvergne-Rhone-Alpes, France"},
    {"gl": "br", "hl": "pt-BR", "location": "Curitiba, State of Parana, Brazil"},
]

for market in MARKETS:
    r = requests.get(
        "https://serpcrypto.com/api/v1/search",
        params={"q": "running shoes", **market},
        headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
        timeout=60,
    )
    r.raise_for_status()
    applied = r.json()["search_parameters"]
    top = r.json().get("organic_results", [])[:1]
    print(applied["gl"], applied.get("google_domain"), [x["link"] for x in top])

Bing도 같은 파라미터를 받나요?

q, gl, hl, device, page는 네, 같습니다. engine=bing와 함께 같은 코드를 사용하면 됩니다. google_domain은 Bing에 적용되지 않으며 무시됩니다. 응답은 같은 구조이고 organic_results과 related_searches이 포함됩니다. 활용 사례는 Bing 페이지를 참고하세요.