이미지 및 주석 표시

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

Geocoding API's SearchDestinations 엔드포인트는 탐색 지점과 출입구를 비롯한 세부 지역의 컨텍스트를 제공합니다. 사용자 환경을 개선하기 위해 응답에 스트리트 뷰 Static API의 매개변수를 포함하여 이러한 위치와 관련된 이미지를 표시할 수 있습니다.

이미지 및 주석 요청

이미지 및 주석 정보를 수신하려면 X-Goog-FieldMask 헤더에 다음 필드를 포함해야 합니다.

cURL 요청 예시

curl -X POST -d '{
  "place": "places/ChIJkU89GL9ZwokRvVjWDQzhaNg"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: destinations.navigationPoints.streetViewThumbnail,destinations.navigationPoints.entranceAnnotation,destinations.entrances.streetViewThumbnail,destinations.entrances.streetViewAnnotation" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

JSON 응답 예시

{
  "destinations": [
    {
      "entrances": [
        {
          "location": {
            "latitude": 40.7406763,
            "longitude": -74.0020733
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJkU89GL9ZwokRvVjWDQzhaNg",
          "streetViewThumbnail": {
            "pano": "EUKaIR67fBVmpsHnXuIevA",
            "widthPx": 400,
            "heightPx": 600,
            "headingDegree": 331.06186,
            "fovDegree": 60
          },
          "streetViewAnnotation": {
            "coordinates": [
              {
                "xPx": 184.7,
                "yPx": 290.4
              },
              {
                "xPx": 213.3,
                "yPx": 289.4
              },
              {
                "xPx": 214.8,
                "yPx": 330.8
              },
              {
                "xPx": 186.0,
                "yPx": 332.5
              }
            ]
          }
        }
      ]
    }
  ]
}

응답의 Entrance 및 NavigationPoint 객체는 다음 필드가 포함된 streetViewThumbnail 필드를 포함할 수 있습니다.

필드 설명 Static API 매개변수
pano 특정 파노라마 ID입니다. pano
widthPx 이미지의 권장 너비입니다. size (너비 부분)
heightPx 이미지의 권장 높이입니다. size (높이 부분)
headingDegree 카메라의 나침반 방향(0~360)입니다. heading
pitchDegree 카메라의 위/아래 각도 (-90~90)입니다. pitch
fovDegree 수평 시야 (0~120)입니다. fov

이미지 요청

스트리트 뷰 이미지를 요청하려면 streetViewThumbnail 객체의 값을 사용하여 Street View Static API의 URL을 구성합니다.

URL 예시

다음은 구성된 스트리트 뷰 Static API URL의 예입니다.

https://maps.googleapis.com/maps/api/streetview?size=400x600&pano=EUKaIR67fBVmpsHnXuIevA&heading=331.06186&fov=60&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

샘플 코드: TypeScript

다음 TypeScript 함수는 Destinations 엔드포인트 출력에서 Static 스트리트 뷰 API URL을 구성하는 방법을 보여줍니다.

interface StreetViewThumbnail {
  pano: string;
  widthPx: number;
  heightPx: number;
  headingDegree: number;
  pitchDegree: number;
  fovDegree: number;
}

function getStreetViewUrl(thumbnail: StreetViewThumbnail, apiKey: string): string {
  const params = new URLSearchParams({
    size: `${thumbnail.widthPx}x${thumbnail.heightPx}`,
    pano: thumbnail.pano,
    heading: thumbnail.headingDegree.toString(),
    pitch: thumbnail.pitchDegree.toString(),
    fov: thumbnail.fovDegree.toString(),
    key: apiKey,
  });

  return `https://maps.googleapis.com/maps/api/streetview?${params.toString()}`;
}

이미지 주석

Entrance 또는 NavigationPoint가 반환되면 streetViewAnnotation 또는 entranceAnnotation 필드에 해당하는 출입구의 이미지 주석도 포함될 수 있습니다. 이렇게 하면 썸네일 이미지 내에서 출입구를 윤곽선으로 표시하는 다각형의 픽셀 좌표가 제공됩니다.

이러한 주석은 클라이언트 측 렌더링 을 위한 것입니다. 이를 사용하여 Static API에서 반환된 이미지 위에 오버레이를 그릴 수 있습니다 (예: SVG 또는 <canvas> 사용).

주석 좌표계

원점 (0,0)은 이미지의 왼쪽 상단 모서리 입니다.

  • xPx: 왼쪽 가장자리에서 가로 거리입니다.
  • yPx: 상단 가장자리에서 세로 거리입니다.

다각형이 올바르게 정렬되도록 하려면 widthPx 및 heightPx에서 지정한 size를 사용하여 Static API에서 이미지를 요청해야 합니다.

샘플 코드: 주석 그리기 (TypeScript 및 SVG)

이 예에서는 TypeScript 및 SVG를 사용하여 출입구 주석 다각형을 스트리트 뷰 이미지에 오버레이하는 방법을 보여줍니다.

TypeScript

interface Coordinate {
  xPx: number;
  yPx: number;
}

interface StreetViewAnnotation {
  coordinates: Coordinate[];
}

function drawAnnotations(annotation: StreetViewAnnotation, width: number, height: number) {
  const svg = document.getElementById('annotation-overlay') as unknown as SVGSVGElement;
  const polygon = document.getElementById('entrance-polygon') as unknown as SVGPolygonElement;

  // Set SVG dimensions to match the image
  svg.setAttribute('width', width.toString());
  svg.setAttribute('height', height.toString());
  svg.setAttribute('viewBox', `0 0 ${width} ${height}`);

  // Construct points string for the polygon
  const points = annotation.coordinates
    .map(coord => `${coord.xPx},${coord.yPx}`)
    .join(' ');

  polygon.setAttribute('points', points);
}

// Example usage:
const annotation = {
  coordinates: [
    {xPx: 184.7, yPx: 290.4},
    {xPx: 213.3, yPx: 289.4},
    {xPx: 214.8, yPx: 330.8},
    {xPx: 186.0, yPx: 332.5}
  ]
};
drawAnnotations(annotation, 400, 600);

HTML

<div style="position: relative; display: inline-block;">
  <!-- The Street View image from the previous step -->
  <img id="street-view-image" src="STREET_VIEW_IMAGE" alt="Street View" style="display: block;">

  <!-- SVG overlay for annotations -->
  <svg id="annotation-overlay" style="position: absolute; top: 0; left: 0; pointer-events: none;">
    <polygon id="entrance-polygon" points="" style="fill:rgba(0, 255, 17, 0.3);stroke:rgba(0, 255, 17, 0.9);stroke-width:3" />
  </svg>
</div>

다음과 비슷한 모습이어야 합니다.

Google 뉴욕시 스트리트 뷰

의견

이는 Geocoding API의 실험용 기능입니다. geocoding-feedback-channel@google.com 으로 의견을 보내주시면 감사하겠습니다.

달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.

최종 업데이트: 2026-04-25(UTC)