자동 완성 (신규)

자동 완성 (신규) 서비스는 HTTP 요청에 대한 응답으로 장소 예상 검색어 및 쿼리 예상 검색어를 반환하는 웹 서비스입니다. 요청에서 검색 영역을 제어하는 텍스트 검색 문자열과 지리적 경계를 지정합니다.

자동 완성 (신규) 서비스는 입력의 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소, Plus Code를 결정할 수 있습니다. 따라서 사용자가 입력할 때 애플리케이션에서 쿼리를 전송하여 즉시 장소 및 쿼리 예상 검색어를 제공할 수 있습니다.

Autocomplete (New) API의 응답에는 두 가지 유형의 예상 검색어가 포함될 수 있습니다.

  • 장소 예상 검색어: 지정된 입력 텍스트 문자열과 검색 지역을 기반으로 비즈니스, 주소, 관심 장소 등의 장소를 제공합니다. 장소 예상 검색어는 기본적으로 반환됩니다.
  • 쿼리 예측: 입력 텍스트 문자열 및 검색 영역과 일치하는 쿼리 문자열입니다. 쿼리 예측은 기본적으로 반환되지 않습니다. includeQueryPredictions 요청 매개변수를 사용하여 쿼리 예측을 응답에 추가합니다.

예를 들어 'Sicilian piz'라는 일부 사용자 입력이 포함되고 검색 영역이 CA 샌프란시스코로 제한된 문자열을 입력으로 사용하여 API를 호출합니다. 그러면 응답에 검색 문자열 및 검색 영역(예: 'Sicilian Pizza Kitchen'이라는 레스토랑)과 일치하는 장소 예상 검색어 목록과 장소에 대한 세부정보가 포함됩니다.

반환된 장소 예상 검색어는 사용자에게 표시되어 원하는 장소를 선택하는 데 도움이 되도록 설계되었습니다. Place Details (New) 요청을 실행하여 반환된 장소 예상 검색어에 대한 자세한 정보를 가져올 수 있습니다.

응답에는 검색 문자열 및 검색 영역(예: '시칠리안 피자 및 파스타')과 일치하는 검색어 예상 검색어 목록도 포함될 수 있습니다. 응답의 각 쿼리 예상 검색어에는 추천 텍스트 검색 문자열이 있는 text 필드가 포함됩니다. 이 문자열을 텍스트 검색 (신규)의 입력으로 사용하여 더 자세한 검색을 수행합니다.

자동 완성 (신규) 요청

Autocomplete (New) 요청은 다음 형식의 URL에 대한 HTTP POST 요청입니다.

https://places.googleapis.com/v1/places:autocomplete

모든 매개변수를 JSON 요청 본문이나 헤더에 POST 요청의 일부로 전달합니다. 예를 들면 다음과 같습니다.

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

자동 완성을 사용하여 요청 (신규)

Places API는 기존의 Autocomplete 및 Query Autocomplete API를 지원합니다. 이러한 API에 익숙하다면 미리보기 버전의 자동 완성 (신규)은 다음과 같이 변경합니다.

  • 새 Autocomplete은 HTTP POST 요청을 사용합니다. HTTP POST 요청의 일부로 요청 본문 또는 헤더에 매개변수를 전달합니다. 반대로 기존 API를 사용할 때는 HTTP GET 요청을 사용하여 URL 매개변수를 전달합니다.
  • 새 자동 완성은 인증 메커니즘으로 API 키와 OAuth 토큰을 모두 지원합니다.
  • 새 자동 완성에서는 JSON만 응답 형식으로 지원됩니다.

다음 표에는 새 Autocomplete로 이름이 변경되거나 수정된 기존 Autocomplete API 및 Query Autocomplete API의 매개변수 또는 더 이상 지원되지 않는 매개변수가 나와 있습니다.

현재 매개변수 새 매개변수 Notes
components includedRegionCodes
language languageCode
location locationBias
ipbias locationBias와 locationRestriction를 모두 생략하면 API가 기본적으로 IP 상세 검색을 사용합니다.
offset inputOffset
radius locationBias 또는 locationRestriction
region regionCode
stricbounds locationRestriction
sessiontoken sessionToken
types includedPrimaryTypes

사용량 한도

미리보기 출시 기간 중에는 프로젝트별로 분당 최대 쿼리 수가 600개로 제한됩니다.

미리보기 출시 지원 옵션

Google은 서비스의 미리보기 버전이나 기능에 대한 지원을 제공할 의무는 없지만 이러한 개발 단계의 요청을 사례별로 고려합니다.

  • 출시 전 버전에는 Google Maps Platform SLA가 적용되지 않습니다.
  • 특히 프로덕션 환경에서 출시 전 버전을 사용하는 경우 대체 메커니즘을 사용하는 것이 좋습니다. 대체 상황의 예로는 할당량 초과, 예기치 않은 응답 코드 및 지연 시간, 기존 자동 완성과 비교 시 예상치 못한 응답이 있습니다.

Issue Tracker를 사용하여 새 기능을 요청하거나 기존 기능의 수정사항을 제안할 수 있습니다. 추가되기를 원하는 기능과 그 기능이 중요하다고 생각하는 이유를 설명하세요. 가능하다면 사용 사례와 이 기능으로 얻을 수 있는 새로운 기회에 관한 구체적인 정보를 포함하세요.

기능에 대한 다른 질문이 있으면 newplacesapi@google.com으로 이메일을 보내 주세요.

응답 정보

Autocomplete (신규)는 JSON 객체를 응답으로 반환합니다. 응답에서 각 항목의 의미는 다음과 같습니다.

  • suggestions 배열에는 감지된 관련성을 기준으로 모든 예상 장소와 검색어가 포함됩니다. 각 장소는 placePrediction 필드로 표시되고 각 쿼리는 queryPrediction 필드로 표시됩니다.
  • placePrediction 필드에는 장소 ID 및 텍스트 설명 등 단일 장소 예상 검색어에 대한 세부정보가 포함됩니다.
  • queryPrediction 필드에는 단일 쿼리 예상 검색어에 대한 자세한 정보가 포함됩니다.

전체 JSON 객체는 다음과 같은 형식입니다.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

필수 매개변수

  • 입력

    검색할 텍스트 문자열입니다. 전체 단어 및 하위 문자열, 장소 이름, 주소, Plus Code를 지정합니다. 자동 완성 (신규) 서비스는 이 문자열을 기준으로 일치 가능성이 높은 항목을 반환하고 감지된 관련성을 기준으로 검색 결과를 정렬합니다.

선택적 매개변수

  • includedPrimaryTypes

    장소는 장소와 연결된 표 A 또는 표 B 유형의 단일 기본 유형만 가질 수 있습니다. 예를 들어 기본 유형은 "mexican_restaurant" 또는 "steak_house"일 수 있습니다.

    기본적으로 API는 장소와 연결된 기본 유형 값에 관계없이 input 매개변수를 기반으로 모든 장소를 반환합니다. includedPrimaryTypes 매개변수를 전달하여 결과를 특정 기본 유형 또는 기본 유형으로 제한합니다.

    이 매개변수를 사용하여 표 A 또는 표 B에서 최대 5개의 유형 값을 지정합니다. 장소는 지정된 기본 유형 값 중 하나와 일치해야 응답에 포함됩니다.

    다음과 같은 경우 INVALID_REQUEST 오류와 함께 요청이 거부됩니다.

    • 5개 이상의 유형이 지정되었습니다.
    • 인식할 수 없는 유형이 지정되었습니다.

  • includeQueryPredictions

    true인 경우 응답에 장소와 예상 검색어가 모두 포함됩니다. 기본값은 false이며 응답에 장소 예상 검색어만 포함됩니다.

  • includedRegionCodes

    최대 15개의 ccTLD ('최상위 도메인') 2자리 값의 배열로 지정된 지정된 지역 목록의 결과만 포함합니다. 생략하면 응답에 제한이 적용되지 않습니다. 예를 들어 리전을 독일과 프랑스로 제한하려면 다음을 실행합니다.

        "includedRegionCodes": ["de", "fr"]

    locationRestriction와 includedRegionCodes를 모두 지정하면 결과는 두 설정이 교차하는 영역에 표시됩니다.

  • inputOffset

    input의 커서 위치를 나타내는 0부터 시작하는 유니코드 문자 오프셋입니다. 커서 위치는 반환되는 예측에 영향을 줄 수 있습니다. 비어 있는 경우 기본값은 input의 길이입니다.

  • languageCode

    결과 반환에 사용할 기본 언어입니다. input에 사용된 언어가 languageCode로 지정된 값과 다르거나 반환된 장소에 현지 언어에서 languageCode로 번역되지 않은 경우 결과는 혼합된 언어일 수 있습니다.

    • IETF BCP-47 언어 코드를 사용하여 기본 언어를 지정해야 합니다.
    • languageCode를 제공하지 않으면 API는 Accept-Language 헤더에 지정된 값을 사용합니다. 둘 다 지정되지 않으면 기본값은 en입니다. 잘못된 언어 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다.
    • 기본 언어는 API가 반환하기로 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 이는 API의 맞춤법 오류 수정 기능에도 영향을 줍니다.
    • API는 사용자 입력을 반영하는 동시에 사용자와 지역 주민이 모두 읽을 수 있는 상세 주소를 제공하려고 합니다. 장소 예상 검색어의 형식은 각 요청의 사용자 입력에 따라 다르게 지정됩니다.
      • input 매개변수의 일치하는 용어가 먼저 선택됩니다. 가능한 경우 languageCode 매개변수로 표시된 언어 환경설정에 맞는 이름을 사용하고 그 외의 경우에는 사용자 입력과 가장 일치하는 이름을 사용합니다.
      • 상세 주소는 input 매개변수의 용어와 일치하도록 일치하는 용어가 선택된 후에만 가능한 경우 사용자가 읽을 수 있는 스크립트의 현지 언어로 형식이 지정됩니다.
      • 다른 모든 주소는 input 매개변수의 용어와 일치하도록 일치하는 검색어를 선택한 후 기본 언어로 반환됩니다. 기본 언어로 이름을 사용할 수 없는 경우 API는 가장 근접한 일치 항목을 사용합니다.

  • locationBias 또는 locationRestriction

    locationBias 또는 locationRestriction 중 하나를 지정하여 검색 영역을 정의할 수 없습니다. locationRestriction는 결과가 포함되어야 하는 지역을 지정하는 것으로, locationBias는 결과가 근처에 있어야 하지만 이 영역 밖에 있을 수 있는 지역을 지정하는 것으로 생각하면 됩니다.

    • locationBias

      검색할 영역을 지정합니다. 이 위치는 바이어스 역할을 하므로 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과를 반환할 수 있습니다.

    • locationRestriction

      검색할 영역을 지정합니다. 지정된 영역 밖의 결과는 반환되지 않습니다.

    locationBias 또는 locationRestriction 영역을 직사각형 표시 영역 또는 원으로 지정합니다.

    • 원은 중심점과 반경(미터)으로 정의됩니다. 반경은 0.0 이상 50000.0 이하여야 합니다. 기본값은 0.0입니다. locationRestriction의 경우 반경을 0.0보다 큰 값으로 설정해야 합니다. 그렇지 않으면 요청에서 결과가 반환되지 않습니다.

      예를 들면 다음과 같습니다.

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • 직사각형은 대각선으로 반대되는 두 개의 low와 높은 지점으로 표시되는 위도-경도 표시 영역입니다. 표시 영역은 닫힌 영역으로 간주되며 표시 영역 내에 경계가 포함됩니다. 위도 경계는 -90도 이상 90도 이하로, 경도 경계는 -180도 이상 180도 이하여야 합니다.

      • low = high인 경우 표시 영역은 단일 점으로 구성됩니다.
      • low.longitude > high.longitude인 경우 경도 범위가 반전됩니다(표시 영역이 경도 180도 선을 교차함).
      • low.longitude = -180도이고 high.longitude = 180도이면 표시 영역에 모든 경도가 포함됩니다.
      • low.longitude = 180도이고 high.longitude = -180도이면 경도 범위는 비어 있습니다.

      low와 high가 모두 채워져야 하며 표시된 상자는 비워 둘 수 없습니다. 표시 영역이 비어 있으면 오류가 발생합니다.

      예를 들어 다음 표시 영역은 뉴욕시를 완전히 둘러쌉니다.

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • 원산지

    목적지까지의 직선 거리를 계산할 출발지입니다 (distanceMeters로 반환됨). 이 값을 생략하면 직선 거리가 반환되지 않습니다. 위도와 경도 좌표로 지정해야 합니다.

    "origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

  • regionCode

    응답 형식을 지정하는 데 사용되는 지역 코드로, 2자리 ccTLD ('최상위 도메인') 값으로 지정됩니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 특별한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)인 반면 ISO 3166-1 코드는 'gb' (기술적으로 '영국 및 북아일랜드'의 엔티티)입니다.

    잘못된 리전 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다. 매개변수는 관련 법률에 따라 결과에 영향을 줄 수 있습니다.

  • sessionToken

    세션 토큰은 자동 완성(신규) 호출을 '세션'으로 추적하는 사용자 생성 문자열입니다. Autocomplete (New)는 세션 토큰을 사용하여 결제 목적의 사용자 자동 완성 검색의 쿼리 및 선택 단계를 별개의 세션으로 그룹화합니다. 자세한 내용은 세션 토큰을 참조하세요.

자동 완성 (신규) 예시

locationRestriction 및 locationBias 사용

API는 기본적으로 IP 상세 검색을 사용하여 검색 영역을 제어합니다. IP 바이어스를 사용하면 API가 기기의 IP 주소를 사용하여 결과를 편중합니다. 필요한 경우 locationRestriction 또는 locationBias 중 하나만 사용하여 검색할 영역을 지정할 수 있습니다.

locationRestriction은 검색할 영역을 지정합니다. 지정된 영역 밖의 결과는 반환되지 않습니다. 다음 예에서는 locationRestriction를 사용하여 샌프란시스코를 중심으로 한 반경 5, 000미터의 원으로 요청을 제한합니다.

curl -X POST -d '{
  "input": "Amoeba",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

지정된 영역 내의 모든 결과는 suggestions 배열에 포함됩니다.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

locationBias를 사용하면 위치가 바이어스 역할을 하므로 지정된 지역 밖의 결과를 포함하여 지정된 위치 주변의 결과를 반환할 수 있습니다. 다음 예에서는 locationBias를 사용하도록 요청을 변경합니다.

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

이제 결과에는 5000미터 반경을 벗어난 결과를 비롯하여 더 많은 항목이 포함됩니다.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

includePrimaryTypes 사용

요청의 결과를 표 A와 표 B에 나열된 특정 유형으로 제한하려면 includedPrimaryTypes 매개변수를 사용합니다. 최대 5개의 값으로 구성된 배열을 지정할 수 있습니다. 생략하면 모든 유형이 반환됩니다.

다음 예에서는 'Soccer'의 input 문자열을 지정하고 includedPrimaryTypes 매개변수를 사용하여 결과를 "sporting_goods_store" 유형의 시설로 제한합니다.

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

includedPrimaryTypes 매개변수를 생략하면 "athletic_field"과 같이 원하지 않는 유형의 시설이 결과에 포함될 수 있습니다.

쿼리 예측 요청

쿼리 예측은 기본적으로 반환되지 않습니다. includeQueryPredictions 요청 매개변수를 사용하여 응답에 쿼리 예측을 추가합니다. 예를 들면 다음과 같습니다.

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

이제 suggestions 배열에 위의 응답 정보에 표시된 대로 장소 예상 검색어와 쿼리 예상 검색어가 모두 포함됩니다. 각 예상 쿼리에는 추천 텍스트 검색 문자열이 포함된 text 필드가 포함됩니다. Text Search (New) 요청을 수행하여 반환된 예상 검색어 중 자세한 정보를 얻을 수 있습니다.

출처 사용

이 예에서는 요청에 origin을 위도와 경도 좌표로 포함합니다. origin를 포함하면 API는 origin에서 목적지까지의 직선 거리가 포함된 distanceMeters 필드를 응답에 포함합니다. 다음 예는 출발지를 샌프란시스코 중심부로 설정합니다.

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

이제 응답에 distanceMeters가 포함됩니다.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}