한 도시의 Google 장소를 100곳까지 받아요

Google 장소 탭이 검색어에 보여 주는 장소를 원하는 도시에서 최대 100곳까지 주소, 좌표, 전화번호, 웹사이트, 평점과 함께 받아요. 장소 20곳마다 1크레딧이에요.

받는 결과

• GOOGLE_PLACES: 태스크 하나가 고른 도시에서 검색어로 Google 장소 탭이 보여 주는 목록을 최대 100곳까지 읽습니다.
• places: 장소마다 name, position, 나온 page와 함께 location(주소, 위도, 경도), phoneNumber, url, mapsUrl, placeId, 평점과 리뷰 수가 담긴 reviews, category, Google이 보여 주는 리뷰 문장이 담깁니다.
• pages: 태스크가 읽은 20곳 단위 페이지 수이고, 이 수만큼 과금됩니다.

동작 방식

query와 city를 보내세요. city는 Reno, Nevada, United States처럼 Google이 쓰는 이름으로 적습니다. 순위 추적 도구가 장소마다 Google의 uule 값을 저장해 두었다면 uule로 보내면 Google이 그 장소에서 검색합니다. country는 시장을 정하고 기본값은 US입니다.

Google은 한 페이지에 장소 20곳을 보여 줍니다. limit로 받을 장소 수를 1~100(기본 20) 사이에서 정하면 태스크가 Google 순서대로 최대 다섯 페이지를 읽습니다. position은 페이지를 넘어 이어서 세고, 뒤 페이지에 다시 나온 장소는 한 번만 셉니다. Google 목록이 limit보다 먼저 끝나면 Google이 보여 준 장소를 모두 받습니다.

태스크는 페이지마다 Google이 검색한 위치를 확인하므로 한 목록의 장소는 모두 같은 도시에서 나옵니다.

이렇게 활용하세요

• 내 업종을 검색했을 때 Google이 내 도시에서 보여 주는 장소 가운데 내 매장이 몇 위인지 local pack의 세 곳 너머까지 추적합니다.
• 같은 검색어를 영업하는 도시마다 보내 시장별 상위 업체를 비교합니다.
• 같은 검색어의 Google AI 개요, AI Mode 답변과 장소 목록을 나란히 놓고 답변이 어떤 장소를 추천하는지 봅니다.
• Playground에서 바로 써 보세요. 검색 탭에서 Google Places를 고르고 도시를 적은 뒤 장소 수를 100곳까지 정합니다.

요청 보내기

API 키를 Authorization 헤더에 넣어 요청을 보냅니다.

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "GOOGLE_PLACES",
    "payload": {
      "query": "Reno attorney",
      "city": "Reno, Nevada, United States",
      "limit": 100,
      "country": "US"
    }
  }'

요청 필드

taskTypestring필수

실행할 엔진입니다. CHATGPT, GOOGLE 같은 값을 넣습니다.

payload.querystring필수

사용자가 검색창에 입력하듯 쓴 검색어입니다.

payload.citystring

검색할 도시입니다. Google이 쓰는 이름으로 적습니다. 예: Reno, Nevada, United States. 최대 100자. 태스크 하나에 city와 uule 중 하나를 씁니다.

payload.uulestring

Google의 위치 값을 w+ 형식 그대로 넣습니다. 순위 추적 도구가 장소마다 저장해 두는 값이고, Google에 그대로 보냅니다.

payload.limitinteger

돌려받을 장소 수, 1~100. 기본값 20(Google 목록 한 페이지).

payload.countrystring

질문할 시장의 두 글자 국가 코드입니다. US, KR, JP 등. 기본값 US.

webhook.urlstring

서버의 HTTPS 주소입니다. 태스크가 끝나는 즉시 결과를 이 주소로 보냅니다.

응답

완료된 태스크는 이런 형태입니다. 길이를 줄여 보여 드립니다.

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "GOOGLE_PLACES",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": 5, "creditsCharged": 5 },
  "response": {
    "places": [
      {
        "name": "Joey Gilbert Law",
        "position": 1,
        "placeId": "ChIJcW7HSupAmYARRnrM6Ap0UtU",
        "location": {
          "address": "405 Marsh Ave, Reno, NV 89509",
          "latitude": 39.519216,
          "longitude": -119.815709
        },
        "phoneNumber": "(775) 210-1501",
        "url": "https://joeygilbertlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=15371476068373133894",
        "reviews": [
          { "rating": 4.4, "count": 381, "providerName": "Google" }
        ],
        "category": "Criminal justice attorney",
        "snippet": "Joey is knowledgeable, straightforward, and fights hard for his clients.",
        "page": 1
      },
      {
        "name": "Viloria, Oliphant, Oster & Aman L.L.P.",
        "position": 2,
        "placeId": "ChIJv8KkdMlAmYARmINKFMPLxbs",
        "location": {
          "address": "327 California Ave, Reno, NV 89509",
          "latitude": 39.520335,
          "longitude": -119.81519
        },
        "phoneNumber": "(775) 515-8480",
        "url": "https://www.renonvlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=13530444694224012184",
        "reviews": [
          { "rating": 4.6, "count": 117, "providerName": "Google" }
        ],
        "category": "Personal injury attorney",
        "snippet": "Tom’s work ethic and knowledge of the legal system is beyond reproach.",
        "page": 1
      },
      "…"
    ],
    "pages": 5,
    "city": "Reno, Nevada, United States"
  }
}

task.statusstring

QUEUED, PROCESSING을 거쳐 답변과 함께 COMPLETED로, 또는 error와 함께 FAILED로 끝납니다.

credits.creditsChargedinteger

끝난 태스크에 청구된 크레딧입니다. 실패한 태스크는 0입니다.

response.placesarray

Google 순서대로 담긴 장소입니다. name, 페이지를 넘어 이어 세는 position, 나온 page와, Google이 보여 주면 placeId, location, phoneNumber, url, mapsUrl, reviews, category, snippet이 담깁니다.

response.pagesinteger

읽은 페이지 수(페이지당 장소 20곳), 1~5. 이 페이지 수만큼 과금됩니다.

결과 받기

요청하면 status가 QUEUED인 태스크가 바로 돌아옵니다. status가 COMPLETED나 FAILED가 될 때까지 GET /v1/async/task/{id}로 조회하거나, webhook.url을 넣어 같은 task, credits, response를 서버로 받으세요. 결과는 태스크가 끝난 뒤 24시간 동안 조회됩니다.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

오류

VALIDATION_ERRORHTTP 422

limit가 1~100 밖에 있거나, city가 비었거나 100자를 넘거나, city를 uule이나 location과 함께 보냈습니다. details에 해당 필드가 나옵니다.

MISSING_API_KEYHTTP 401

Authorization 헤더가 빠졌거나, 키가 잘못됐거나 만료 또는 폐기됐습니다.

INSUFFICIENT_CREDITSHTTP 402

잔액이 태스크 가격보다 적습니다. 크레딧을 충전하거나 플랜을 올린 뒤 다시 보내세요.

요금

장소 20곳 한 페이지마다 1크레딧이 차감되므로 100곳은 5크레딧입니다. 제출할 때 limit에 필요한 크레딧을 잡아 두고, 완료되면 읽은 페이지만큼 차감합니다. 2페이지에서 끝난 목록은 2크레딧입니다.