유효한 주소 또는 동영상 ID가 주어지면 lookupVideo 메서드는 항공 뷰 API 동영상 집합을 식별하는 URI를 반환합니다. lookupVideo 메서드는 Google에서 해당 위치의 동영상을 이미 생성한 경우에만 URI를 반환합니다.
동영상이 있는지 확인하려면 lookupVideoMetadata 메서드를 사용합니다.
API 사용 방법
URL 인코딩된 미국 우편 주소 또는 videoId를 전달하여 이 엔드포인트를 호출합니다.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?key=YOUR_API_KEY&address=POSTAL_ADDRESS "
그러면 API가 다음 세 가지 응답 중 하나를 반환합니다.
동영상이 있는 경우
lookupVideo는ACTIVE의 처리 상태와 지원되는 모든 미디어 유형의 가로 및 세로 URI, 메타데이터를 반환합니다.동영상이 YouTube 시스템에 있지만 아직 완전히 렌더링되지 않은 경우
lookupVideo는PROCESSING의 처리 상태와videoId를 반환합니다.videoId를 사용하면 렌더링이 완료된 후 동영상을 가져올 수 있습니다.동영상이 아직 존재하지 않으면 API는 404 상태 코드를 반환합니다. 이 경우
renderVideo를 호출하여 새 동영상을 생성할 수 있습니다.
반환된 동영상 URI를 사용하는 방법
주소당 한 번 lookupVideo 메서드를 호출하거나 뷰당 videoID를 호출합니다. 대답의 동영상 URI는 단기 URI라고 하며 짧은 시간이 지나면 만료됩니다.
Google에서는 동영상을 자주 업데이트합니다. 따라서 고객에게 최신 콘텐츠를 표시하려면 동영상을 표시할 때마다 lookupVideo 메서드를 호출하세요.
접근성 지원 동영상
접근성을 지원하기 위해 고객에게 항공 뷰 동영상을 표시할 때 스크립트 또는 동영상 설명을 추가하는 것이 좋습니다. 이렇게 하면 스크린 리더가 사용자에게 스크립트 또는 설명을 알릴 수 있습니다.
예를 들어 다음과 같은 형식으로 설명을 추가합니다.
'Google 지도에서 제공하는 주소의 포토리얼리스틱 항공 뷰입니다.'
주소 대신 다음과 같은 형식으로 동영상 설명을 추가할 수 있습니다.
'이 이미지는 Google 지도에서 제공하는 뉴욕 엠파이어 스테이트 빌딩의 포토리얼리스틱 항공 뷰입니다.'
나중에 사용할 수 있도록 동영상 ID 저장
항공 뷰 API의 서비스별 약관에 따라 항공 뷰 API 동영상 ID에는 Google Maps Platform 서비스 약관의 3.2.3(b)(캐싱 금지)항에 명시된 캐싱 제한사항이 적용되지 않습니다. 따라서 나중에 사용하기 위해 동영상 ID 값을 저장할 수 있습니다.
주소를 전달하는 요청 예
다음 코드 샘플은 600 Montgomery St, San Francisco, CA 94111에 있는 트랜스아메리카 피라미드의 항공 뷰 동영상을 요청합니다.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?key=YOUR_API_KEY&address=600%20Montgomery%20St%2C%20San%20Francisco%2C%20CA%2094111"
응답 예
다음 JSON 예시는 lookupVideo 요청에 대한 가능한 모든 응답을 나타냅니다.
동영상 찾음
요청한 동영상이 있는 경우 API는 URI 목록을 반환하며, 각 URI는 요청한 동영상의 다른 형식이나 버전에 연결됩니다. 다양한 형식에 대해 알아보려면 MPEG-DASH란 무엇인가요? | HLS와 DASH 비교를 참고하세요.
{
"uris": {
"IMAGE": {
"landscapeUri": "https://www.gstatic.com/aerialview/thumbnail/-1202461100507922431.jpg?sqp=CKiU6qIGGPQD&rs=AHRQkOe1j6EA5Q3WzJgDluv8AXbNlZ8M-g",
"portraitUri": "https://www.gstatic.com/aerialview/thumbnail/2256303413312618497.jpg?sqp=CKiU6qIGGPQD&rs=AHRQkOelSBTTVgOmFrSZ71c1xjyuoSBAAA"
},
"MP4_HIGH": {
"landscapeUri": "https://rr1---sn-p5qs7nzy.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZKvJBpnc-LYP8v6T-AM&ip=0.0.0.0&id=5f50000000000001&itag=375&source=aerial_view&mh=dX&mm=31&mn=sn-p5qs7nzy&ms=au&mv=D&mvi=1&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=37357139&dur=40.016&lmt=1683384545351664&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRgIhAOhUzpUZGXThRz481S5YAVoy7d7V29-8GDRWLdDEtzagAiEA5laBMqKNnoPCeTHFVT56FYQ5MZp7pZTtDNp9tSJffyc=&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgVqK6hzOoDaTnWt4UmIQgXOyGCc5Pxf4tmp2t6YzwkrQCIQCCOsPpfT2g_BT32Ki_iMwwBb2IhoquVISoHbBMI5_dAw==",
"portraitUri": "https://rr5---sn-p5qlsn7s.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZJiuBo3g-LYPhtaG6AU&ip=0.0.0.0&id=9f50000000000001&itag=375&source=aerial_view&mh=D3&mm=31&mn=sn-p5qlsn7s&ms=au&mv=D&mvi=5&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=11844099&dur=40.016&lmt=1683384626250758&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRgIhAPP030ASCfKrXHpu72d78SBN_3T-7jKQ5_OjAvVzvYLaAiEAhEDAo689v0DWSCkfxxD8oU2iJVifC25Q7gQplx5_25U=&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgREl7bSQ_z9Y86A_bRnX1RdQqoIbwgjV2rEkhLlNilBICIQC9amH8IwmRdbbcCUxnSttBjcy_4BwiBBbSd_PM1KgICw=="
},
"MP4_LOW": {
"landscapeUri": "https://rr1---sn-p5qs7nzy.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZKvJBpnc-LYP8v6T-AM&ip=0.0.0.0&id=5f50000000000001&itag=134&source=aerial_view&mh=dX&mm=31&mn=sn-p5qs7nzy&ms=au&mv=D&mvi=1&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=3152145&dur=39.999&lmt=1683384843730359&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRAIgVDf8P_aMLthAC6ASciANODNo7p7IqofngIgCUnfUofYCICV7JexvuPTnaqOfShKIL33uhtzIfnfOj2LgfpY0zKdx&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIhAM2jKSXegkPbIFD4L7H6FeBz5ytYtMkXNfowGlAB9aL2AiA3DQJIeoTfs3EOIPMfDBCGm7v_vWTruRBjXLN4lRIa-Q==",
"portraitUri": "https://rr5---sn-p5qlsn7s.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZJiuBo3g-LYPhtaG6AU&ip=0.0.0.0&id=9f50000000000001&itag=134&source=aerial_view&mh=D3&mm=31&mn=sn-p5qlsn7s&ms=au&mv=D&mvi=5&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=1002125&dur=39.999&lmt=1683384248881200&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRAIgYRyzRjtsGYFcodlU4-SvJ9GRgx97MF1nFlhoY74YtN4CIF5GuHAEnKqPoZBt5qYO2jur46q1OMEjvjtYATwNHMtD&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRgIhAPoXkJ5-MQTNCy19W1zJu8Hi8eo-eYw-5kH-AbFpAsuTAiEAi2EmxfUwfYtPlTQe0jWFVxc7yKMMz0Bqidcf2ZRvYU4="
},
"MP4_MEDIUM": {
"landscapeUri": "https://rr1---sn-p5qs7nzy.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZKvJBpnc-LYP8v6T-AM&ip=0.0.0.0&id=5f50000000000001&itag=374&source=aerial_view&mh=dX&mm=31&mn=sn-p5qs7nzy&ms=au&mv=D&mvi=1&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=25879743&dur=40.016&lmt=1683384621721411&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRQIhANzPUc2SwvlDZ-nyhxNfY8CGVjyitnfpS7MvbXb_f5kSAiAVArz85QjBBAZw-8ugFPIggKCO54IhR6xDg4rfJIh1Tw==&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgJJyNxWDuqLZ89X5wThN1IsVJyvyZ7Qw1Z4jqhCyahjgCIQD9hOjN3hDvX3CN5LiNkoLm-GGAuriUtv0PhtREc7yTVQ==",
"portraitUri": "https://rr5---sn-p5qlsn7s.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZJiuBo3g-LYPhtaG6AU&ip=0.0.0.0&id=9f50000000000001&itag=374&source=aerial_view&mh=D3&mm=31&mn=sn-p5qlsn7s&ms=au&mv=D&mvi=5&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=8228161&dur=40.016&lmt=1683384373331986&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRQIgKsfEQB3GbLqYP5tmHwmkMVqVlfcNl7SBiuBqRw748VsCIQDgkwyNF4jOuOjoX5Qw6TgbpdIPhqS-EvCZ2g2JWPYpbw==&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgHdDEnopIcI2jzLkRLOaKz8Cq1Pwm2yl3nJzaru1dBEsCIQCgor9bkMfAeULTq3EwjzCGjB_RvGBqhGfhJblbBloJpg=="
},
"HLS": {
"landscapeUri": "https://manifest.googlevideo.com/api/manifest/hls_variant/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/playlist_type/LIVE/sparams/expire,ei,ip,id,source,susc,vprv,itag,playlist_type/sig/AOq0QJ8wRgIhAKreaNNOkePt9uVonHcqKIXqUe0TQSA1fcI6BWJexJ2hAiEAv9cj6N9iXI0bH6Ke4fz4XWDtrxVCMgrkGijpsLMpvy8%3D/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRgIhAMbA_78Uc_HUS8LaVWnJB4Qg7ZKO5IZECuhldckmJ3hPAiEA-GR-0w1zuyFHpvaF1LZBuWgpUM55iosY0KF9MMsePDE%3D/file/index.m3u8",
"portraitUri": "https://manifest.googlevideo.com/api/manifest/hls_variant/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/playlist_type/LIVE/sparams/expire,ei,ip,id,source,susc,vprv,itag,playlist_type/sig/AOq0QJ8wRgIhAKreaNNOkePt9uVonHcqKIXqUe0TQSA1fcI6BWJexJ2hAiEAv9cj6N9iXI0bH6Ke4fz4XWDtrxVCMgrkGijpsLMpvy8%3D/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRgIhAMbA_78Uc_HUS8LaVWnJB4Qg7ZKO5IZECuhldckmJ3hPAiEA-GR-0w1zuyFHpvaF1LZBuWgpUM55iosY0KF9MMsePDE%3D/file/index.m3u8"
},
"DASH": {
"landscapeUri": "https://manifest.googlevideo.com/api/manifest/dash/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/sparams/expire,ei,ip,id,source,susc,vprv,itag/sig/AOq0QJ8wRAIgCClKKnnVXeNnUHirpyxkegs8XSw5bq5e2VHWu-2NGtkCIBvXoHxlfTVmIvB4F9mlxn9EnJxPrcPGo1yIrS-_zbBu/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRQIhAIU_a8wIuPfzMXy1selgJ1bRz1ffXm0YQeFshe0ijAzhAiAPzhkpOjm-IGubZ-Z7o3W_U7lAjR6OkEpWvNEFCRzUVg%3D%3D",
"portraitUri": "https://manifest.googlevideo.com/api/manifest/dash/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/sparams/expire,ei,ip,id,source,susc,vprv,itag/sig/AOq0QJ8wRAIgCClKKnnVXeNnUHirpyxkegs8XSw5bq5e2VHWu-2NGtkCIBvXoHxlfTVmIvB4F9mlxn9EnJxPrcPGo1yIrS-_zbBu/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRQIhAIU_a8wIuPfzMXy1selgJ1bRz1ffXm0YQeFshe0ijAzhAiAPzhkpOjm-IGubZ-Z7o3W_U7lAjR6OkEpWvNEFCRzUVg%3D%3D"
}
},
"state": "ACTIVE",
"metadata": {
"videoId": "-wVXGP6Hkogfqz6sZulUf3",
"captureDate": {
"year": 2022,
"month": 10,
"day": 24
},
"duration": "40s"
}
}
동영상에 액세스하려면 다음 도메인을 허용 목록에 추가해야 합니다.
*.gstatic.com*.googlevideo.com
동영상을 찾을 수 없습니다.
위치에 3D 이미지가 제공되는지 여부에 따라 '동영상을 찾을 수 없음'이라는 응답이 두 가지로 나뉩니다.
렌더링되지 않음
동영상이 이전에 렌더링되지 않았으므로 아직 Google 데이터베이스에 없습니다.
{
"error": {
"code": 404,
"message": "Video not found.",
"status": "NOT_FOUND"
}
}
3D 이미지가 없음
Google에서 이미 동영상을 렌더링하려고 시도했지만 해당 주소에 3D 이미지가 제공되지 않아 실패했습니다.
{
"error": {
"code": 404,
"message": "Video not found: No 3d imagery.",
"status": "NOT_FOUND"
}
}
렌더링 진행 중
state이 PROCESSING로 설정되어 있으므로 시스템에서 아직 렌더링 요청을 처리하는 중입니다. videoId를 가져오고 lookupVideo를 호출하여 동영상을 가져올 수 있습니다.
{
"state": "PROCESSING",
"metadata": {
"videoId": "u-zlVPiScvcD8BYmIVyxoF"
}
}
렌더링 프로세스는 1시간에서 몇 시간까지 걸릴 수 있습니다. 동영상이 아직 처리 중인 경우 lookupVideo를 사용하여 동영상 상태가 ACTIVE 상태를 반환할 때까지 폴링할 수 있습니다.
폴링하려면 videoId을 전달하여 lookupVideo에 요청합니다. 렌더링에는 몇 시간이 걸릴 수 있으므로 지수 백오프를 사용하여 호출 간격을 늘리세요.
videoId를 전달하는 요청 예시
lookupVideo를 호출하고 주소에 대한 항공 뷰 동영상이 없음을 알게 되면 해당 주소로 renderVideo를 호출할 수 있습니다.
renderVideo은 videoId이 포함된 VideoMetadata 객체를 반환합니다. 나중에 주소 대신 videoId를 사용하여 lookupVideo에 전달하여 동영상을 가져올 수 있습니다.
다음 코드 예는 lookupVideo를 호출하여 videoId을 전달하는 방법을 보여줍니다.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?key=YOUR_API_KEY&videoId=VIDEO_ID "