Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

텍스트 검색(신규)

플랫폼 선택: Android iOS JavaScript 웹 서비스

유럽 경제 지역 (EEA) 개발자

텍스트 검색 (신규)은 텍스트 쿼리를 받아 일치하는 장소의 목록을 반환합니다.

텍스트 검색(신규)은 문자열(예: '뉴욕의 피자', '오타와 근처의 신발 가게' 또는 '중앙로 123')을 기반으로 일련의 장소에 대한 정보를 반환하는 웹 서비스입니다. 이 서비스는 사전에 설정된 텍스트 문자열 및 특정 위치와 일치하는 장소의 목록을 반환합니다. 텍스트 검색(신규)을 사용하면 유형별로 장소를 검색하고 영업시간 및 평점과 같은 기준으로 필터링하고 검색 결과를 특정 위치로 제한하거나 특정 위치에 집중된 결과를 얻을 수 있습니다.

텍스트 검색 (신규)을 사용하려면 Google Cloud 프로젝트에서 'Places API (신규)'를 사용 설정해야 합니다. 자세한 내용은 시작하기를 참고하세요.

텍스트 쿼리로 장소 찾기

텍스트 쿼리 또는 전화번호에서 장소 목록을 반환하려면 searchByText를 호출합니다. 요청을 사용하여 검색 매개변수를 지정한 다음 searchByText()를 호출하세요. 결과는 Place 객체의 목록으로 반환되며, 이 목록에서 장소 세부정보를 얻을 수 있습니다. 다음 스니펫은 요청 및 searchByText 호출의 예를 보여줍니다.

TypeScript

const request = {
    textQuery: query,
    fields: ['displayName', 'location', 'businessStatus'],
    includedType: '', // Restrict query to a specific type (leave blank for any).
    useStrictTypeFiltering: true,
    locationRestriction: map.getBounds(),
    isOpenNow: true,
    language: 'en-US',
    maxResultCount: 8,
    minRating: 1, // Specify a minimum rating.
    region: 'us',
};

const { places } = await Place.searchByText(request);index.ts

JavaScript

const request = {
    textQuery: query,
    fields: ['displayName', 'location', 'businessStatus'],
    includedType: '', // Restrict query to a specific type (leave blank for any).
    useStrictTypeFiltering: true,
    locationRestriction: map.getBounds(),
    isOpenNow: true,
    language: 'en-US',
    maxResultCount: 8,
    minRating: 1, // Specify a minimum rating.
    region: 'us',
};

const { places } = await Place.searchByText(request);index.js

textQuery 매개변수를 사용하여 검색할 텍스트 쿼리 또는 전화번호를 지정합니다.
fields 매개변수 (필수)를 사용하여 하나 이상의 데이터 필드가 쉼표로 구분된 목록을 카멜 표기법으로 지정합니다. 요청하는 필드에 따라 요청 가격이 설정됩니다. 데이터 필드 선택을 참조하세요.
includedType 매개변수를 사용하여 지정된 유형의 결과만 반환합니다.
locationBias 또는 locationRestriction를 사용하여 텍스트 검색 결과를 특정 지역으로 상세검색하거나 제한합니다.

속성의 전체 목록을 확인합니다.

쿼리에 전화번호가 포함되어 있으면 지역 매개변수를 설정해야 합니다. 예를 들어 전화번호를 사용하여 일본의 장소를 검색하고 요청 도메인이 jp인 경우 region 매개변수를 'jp'로 설정해야 합니다. 요청에 region이 누락된 경우 API에서 기본적으로 미국 ('us') 지역을 지정합니다.

결과는 Place 객체의 목록으로 반환되며, 이 목록에서 장소 세부정보를 얻을 수 있습니다.

예

다음 예에서는 제공된 쿼리 텍스트로 searchByText를 호출한 다음 클릭 가능한 마커로 지도를 채워 결과를 보여줍니다.

TypeScript

let map: google.maps.Map;
let markers: Record<string, google.maps.marker.AdvancedMarkerElement> = {};
let infoWindow: google.maps.InfoWindow;

async function init() {
    const [{ Map, InfoWindow }, { ControlPosition }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('core'),
    ]);

    const center = { lat: 37.4161493, lng: -122.0812166 };
    map = new Map(document.getElementById('map')!, {
        center,
        zoom: 11,
        mapTypeControl: false,
        mapId: 'DEMO_MAP_ID',
    });

    const textInput = document.getElementById('text-input') as HTMLInputElement;
    const textInputButton = document.getElementById(
        'text-input-button'
    ) as HTMLButtonElement;
    const card = document.getElementById('text-input-card')!;
    map.controls[ControlPosition.TOP_LEFT].push(card);

    textInputButton.addEventListener('click', () => {
        void findPlaces(textInput.value);
    });

    textInput.addEventListener('keydown', (event) => {
        if (event.key === 'Enter') {
            void findPlaces(textInput.value);
        }
    });

    infoWindow = new InfoWindow();
}

async function findPlaces(query: string) {
    const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('places'),
        google.maps.importLibrary('marker'),
    ]);

    const request = {
        textQuery: query,
        fields: ['displayName', 'location', 'businessStatus'],
        includedType: '', // Restrict query to a specific type (leave blank for any).
        useStrictTypeFiltering: true,
        locationRestriction: map.getBounds(),
        isOpenNow: true,
        language: 'en-US',
        maxResultCount: 8,
        minRating: 1, // Specify a minimum rating.
        region: 'us',
    };

    const { places } = await Place.searchByText(request);

    if (places.length) {
        const { LatLngBounds } = await google.maps.importLibrary('core');
        const bounds = new LatLngBounds();

        // First remove all existing markers.
        for (const id in markers) {
            markers[id].map = null;
        }
        markers = {};

        // Loop through and get all the results.
        places.forEach((place: google.maps.places.Place) => {
            const marker = new AdvancedMarkerElement({
                map,
                position: place.location,
                title: place.displayName,
                gmpClickable: true,
            });
            markers[place.id] = marker;

            marker.addEventListener('gmp-click', () => {
                map.panTo(place.location!);
                updateInfoWindow(place.displayName!, place.id, marker);
            });

            if (place.location != null) {
                bounds.extend(place.location);
            }
        });

        map.fitBounds(bounds);
    } else {
        console.log('No results');
    }
}

// Helper function to create an info window.
function updateInfoWindow(
    title: string | Element | null,
    content: string | Element | null,
    anchor: google.maps.marker.AdvancedMarkerElement
) {
    infoWindow.setContent(content);
    infoWindow.setHeaderContent(title);
    infoWindow.open({
        map,
        anchor,
        shouldFocus: false,
    });
}

void init();index.ts

JavaScript

let map;
let markers = {};
let infoWindow;

async function init() {
    const [{ Map, InfoWindow }, { ControlPosition }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('core'),
    ]);

    const center = { lat: 37.4161493, lng: -122.0812166 };
    map = new Map(document.getElementById('map'), {
        center,
        zoom: 11,
        mapTypeControl: false,
        mapId: 'DEMO_MAP_ID',
    });

    const textInput = document.getElementById('text-input');
    const textInputButton = document.getElementById('text-input-button');
    const card = document.getElementById('text-input-card');
    map.controls[ControlPosition.TOP_LEFT].push(card);

    textInputButton.addEventListener('click', () => {
        void findPlaces(textInput.value);
    });

    textInput.addEventListener('keydown', (event) => {
        if (event.key === 'Enter') {
            void findPlaces(textInput.value);
        }
    });

    infoWindow = new InfoWindow();
}

async function findPlaces(query) {
    const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('places'),
        google.maps.importLibrary('marker'),
    ]);

    const request = {
        textQuery: query,
        fields: ['displayName', 'location', 'businessStatus'],
        includedType: '', // Restrict query to a specific type (leave blank for any).
        useStrictTypeFiltering: true,
        locationRestriction: map.getBounds(),
        isOpenNow: true,
        language: 'en-US',
        maxResultCount: 8,
        minRating: 1, // Specify a minimum rating.
        region: 'us',
    };

    const { places } = await Place.searchByText(request);

    if (places.length) {
        const { LatLngBounds } = await google.maps.importLibrary('core');
        const bounds = new LatLngBounds();

        // First remove all existing markers.
        for (const id in markers) {
            markers[id].map = null;
        }
        markers = {};

        // Loop through and get all the results.
        places.forEach((place) => {
            const marker = new AdvancedMarkerElement({
                map,
                position: place.location,
                title: place.displayName,
                gmpClickable: true,
            });
            markers[place.id] = marker;

            marker.addEventListener('gmp-click', () => {
                map.panTo(place.location);
                updateInfoWindow(place.displayName, place.id, marker);
            });

            if (place.location != null) {
                bounds.extend(place.location);
            }
        });

        map.fitBounds(bounds);
    } else {
        console.log('No results');
    }
}

// Helper function to create an info window.
function updateInfoWindow(title, content, anchor) {
    infoWindow.setContent(content);
    infoWindow.setHeaderContent(title);
    infoWindow.open({
        map,
        anchor,
        shouldFocus: false,
    });
}

void init();index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

#text-input-card {
    width: 25%;
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 5px;
    font-family: Roboto, sans-serif;
    font-size: large;
    font-weight: bold;
}

#text-input {
    width: 100%;
    padding: 10px;
    margin: 0;
    box-sizing: border-box;
}

#text-input-button {
    display: inline-block;
    margin-top: 0.5rem;
    width: auto;
    padding: 0.6rem 0.75rem;
    font-size: 0.875rem;
    font-weight: 500;
    color: #fff;
    background-color: #2563eb;
    border: none;
    border-radius: 0.375rem;
    cursor: pointer;
    transition: background-color 0.15s ease-in-out;
    text-align: center;
}
style.css

HTML

<html>
    <head>
        <title>Text Search</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <div id="text-input-card">
            <input
                type="text"
                id="text-input"
                placeholder="Search for a place" />
            <input type="button" id="text-input-button" value="Search" />
        </div>
        <div id="map"></div>
    </body>
</html>index.html

데이터 필드 선택

요청하는 필드에 따라 각 검색 요청의 가격이 설정됩니다. 요청은 요청된 필드 중 가장 높은 SKU로 한 번 청구됩니다. 예를 들어 fields에 reviews를 추가하면 전체 요청이 텍스트 검색 Enterprise + Atmosphere로 청구됩니다.

검색 요청을 텍스트 검색 Pro로 유지하려면 검색 결과에 표시되는 필드(예: id, displayName, formattedAddress, location)만 요청하세요.

사용자가 장소를 선택하면 해당 장소에서 fetchFields()를 호출하여 reviews, nationalPhoneNumber 또는 websiteURI와 같은 필드를 가져옵니다. 각 fetchFields() 호출은 별도의 장소 세부정보 요청이며, 요청하는 필드 중 가장 높은 SKU로 청구됩니다. 이 접근 방식으로 비용을 절감할 수 있는지 여부는 사용자가 여는 장소의 수에 따라 달라집니다.

각 SKU를 트리거하는 필드

다음 필드는 텍스트 검색 Essentials(ID만 해당) SKU를 트리거합니다.

id
다음 필드는 텍스트 검색 Pro SKU를 트리거합니다.

accessibilityOptions
addressComponents
adrFormatAddress
businessStatus
displayName
formattedAddress
googleMapsUri
iconBackgroundColor
location
photos
plusCode
svgIconMaskURI
types
utcOffsetMinutes
viewport
다음 필드는 텍스트 검색 Enterprise SKU를 트리거합니다.

internationalPhoneNumber
nationalPhoneNumber
priceLevel
rating
regularOpeningHours
userRatingCount
websiteURI
다음 필드는 텍스트 검색 Enterprise + Atmosphere SKU를 트리거합니다.

allowsDogs
editorialSummary
evChargeOptions
fuelOptions
hasCurbsidePickup
hasDelivery
hasDineIn
hasLiveMusic
hasMenuForChildren
hasOutdoorSeating
hasRestroom
hasTakeout
hasWifi
isGoodForChildren
isGoodForGroups
isGoodForWatchingSports
isReservable
parkingOptions
paymentOptions
reviews
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine

모든 필드의 SKU는 장소 클래스 데이터 필드를 참고하세요.

텍스트 검색(신규) 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

텍스트 쿼리로 장소 찾기

TypeScript

JavaScript

예

TypeScript

JavaScript

CSS

HTML

데이터 필드 선택

각 SKU를 트리거하는 필드

텍스트 검색(신규)