> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google 장소 검색 결과 API (GOOGLE_PLACES)

> 지역 검색에 대해 Google 장소 목록에 나오는 장소를, 고른 도시 기준으로 최대 100개까지 받습니다.

`GOOGLE_PLACES`는 검색어에 대해 Google 검색의 장소 탭이 보여 주는 장소 목록을 반환합니다. 로컬 팩 아래의 "장소 더보기"로 열리는 목록입니다. 장소 20개씩 최대 5페이지를 읽고 모든 페이지를 같은 도시에서 검색하므로, 그 도시에서 Google이 매긴 순서대로 장소를 최대 100개 받습니다. 도시 전체 지역 목록에서 업체의 순위를 추적하거나, 한 도시에서 Google이 어떤 서비스로 보여 주는 업체 목록을 모을 때 쓰세요.

| | |
| - | - |
| `taskType` | `GOOGLE_PLACES` |
| 입력 | `query`(필수), `city` 또는 `uule`, `limit`, `country` |
| 크레딧 | 읽은 장소 페이지당 1. 한 페이지에 장소 20개가 담깁니다. |
| 국가 | 기본값 `US`. 모든 ISO 3166-1 alpha-2 코드를 받습니다. |
| 위치 | `city`나 `uule`로 지정합니다. [지역과 위치](https://docs.querying.ai/ko/engines/capacity.md)를 참고하세요. |

## 요청

아래 요청은 로드아일랜드주 맨빌에서 장기 요양 시설을 검색할 때 Google이 보여 주는 장소를 앞에서부터 100개 받습니다.

```bash theme={"theme":"css-variables"}
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": "long term care near me", "city": "Manville, Rhode Island, United States", "limit": 100 } }'
```

장소마다 Google의 `uule`을 저장해 두는 시스템이라면 `city` 대신 그 값을 보내세요. 아래 값은 네바다주 리노입니다.

```bash theme={"theme":"css-variables"}
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", "uule": "w+CAIQICIbUmVubywgTmV2YWRhLCBVbml0ZWQgU3RhdGVz", "limit": 100 } }'
```

태스크는 비동기로 실행됩니다. 결과는 [비동기 태스크](https://docs.querying.ai/ko/concepts/async-tasks.md)에 설명한 방법으로 읽으세요. `limit: 100` 태스크는 보통 1\~2분 안에 완료됩니다.

## 파라미터

| 필드 | 필수 | 설명 |
| - | - | - |
| `query` | 예 | 검색어, 1\~100,000자. `query`가 없으면 `prompt`를 받습니다. |
| `city` | 아니요 | 검색 기준 장소. `"Reno, Nevada, United States"`처럼 Google이 장소를 부르는 이름(도시, 주나 지역, 국가)으로 씁니다. 100자 이하. 결과의 `city`에 같은 값을 돌려줍니다. |
| `uule` | 아니요 | Google의 위치 파라미터(`w+` 형식). 순위 추적 도구가 저장해 둔 값을 그대로 Google에 보냅니다. `city`와 `uule` 중 하나를 보내세요. 결과의 `uule`에 같은 값을 돌려줍니다. |
| `limit` | 아니요 | 반환할 장소 수, 1\~100의 정수. 기본값은 한 페이지인 `20`입니다. 전체 목록은 `100`을 보내세요. |
| `country` | 아니요 | 검색할 Google 시장. 기본값은 `US`입니다. |

`city`와 `uule`을 모두 생략하면 Google이 검색 위치를 정합니다.

## 응답

예를 들어 위의 맨빌 요청은 다음과 같습니다.

```json theme={"theme":"css-variables"}
{
  "places": [
    {
      "position": 1,
      "page": 1,
      "name": "...",
      "placeId": "...",
      "location": { "address": "...", "...": "..." },
      "mapsUrl": "https://maps.google.com/?cid=...",
      "reviews": [{ "...": "..." }],
      "category": "..."
    },
    { "position": 21, "page": 2, "...": "..." }
  ],
  "pages": 5,
  "city": "Manville, Rhode Island, United States"
}
```

| 필드 | 설명 |
| - | - |
| `places` | 항상 있습니다. Google이 보여 준 순서입니다. 장소마다 [Google 검색](https://docs.querying.ai/ko/engines/google-serp.md)의 `map`에 담기는 로컬 팩 장소와 같은 필드가 Google이 보여 준 만큼 담깁니다: `name`, `placeId`, `location` (`address`, `latitude`, `longitude`), `phoneNumber`, `url`, `mapsUrl`, `reviews`, `category`, `price`, `snippet`, `image`. |
| `places[].position` | 목록 전체에서의 순위, 1부터. 페이지를 넘어 이어서 셉니다. |
| `places[].page` | 장소가 나온 장소 페이지, 1\~5. |
| `pages` | 읽은 장소 페이지 수. 이 수만큼 과금됩니다. |
| `googleLocation` | Google이 검색 위치로 표시한 장소. 페이지에 위치가 표시될 때만 담깁니다. |
| `city` | 보낸 경우 보낸 `city`. |
| `uule` | 보낸 경우 보낸 `uule`. |

뒤 페이지에 다시 나온 장소는 한 번만 셉니다. `limit`에 이르기 전에 Google의 목록이 끝나면 `places`에 Google이 보여 준 장소가 모두 담깁니다. 작은 도시는 100개보다 적은 경우가 많습니다. Google이 장소에 표시하지 않은 필드는 생략합니다. `name`, `position`, `page`를 제외한 모든 필드를 선택 필드로 다루세요.

## 크레딧

읽은 장소 페이지마다 1크레딧입니다. 제출할 때 `limit`에 필요한 페이지 수(장소 20개당 1페이지)만큼 크레딧을 보류합니다. 기본값은 1, `limit: 100`은 5입니다. 완료되면 실제로 읽은 페이지 수만큼 과금하므로, Google의 목록이 3페이지에서 끝나면 3크레딧입니다. 실패한 태스크는 0크레딧입니다. [크레딧과 한도](https://docs.querying.ai/ko/concepts/credits-and-limits.md)를 참고하세요.

## 제한과 오류

* 완료된 태스크의 `places`가 비어 있으면 그 위치에서 Google이 그 검색어에 장소를 하나도 보여 주지 않았다는 뜻입니다. 반환하기 전에 다른 브라우저에서 한 번 더 확인하며, 1크레딧이 과금됩니다.
* 1\~100을 벗어난 `limit`, 비어 있거나 100자를 넘는 `city`, `uule`이나 `location`과 함께 보낸 `city`는 `422 VALIDATION_ERROR`를 반환합니다.
* `w+` 형식의 UULE가 아닌 `uule`은 `400 VALIDATION_ERROR`를 반환합니다.
* `location`은 `422`를 반환합니다. 장소는 `city`나 `uule`로 지정하세요.
* `include.rawResponse`는 효과가 없고, `include.html`과 `include.analysis`는 `422`를 반환합니다. [Markdown과 원본 응답](https://docs.querying.ai/ko/engines/response-options.md)을 참고하세요.
* 그 밖의 요청 오류는 [오류](https://docs.querying.ai/ko/concepts/errors.md)에 정리되어 있습니다.

## 관련 문서

* 로컬 팩이 담긴 결과 페이지 하나를 받는 [Google 검색](https://docs.querying.ai/ko/engines/google-serp.md)
* [지역과 위치](https://docs.querying.ai/ko/engines/capacity.md)
* [크레딧과 한도](https://docs.querying.ai/ko/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.