유효한 주소 또는 동영상 ID가 주어지면 lookupVideo 메서드는 Aerial View API 동영상 집합을 식별하는 URI를 반환합니다. lookupVideo 메서드는 Google에서 해당 위치의 동영상을 이미 생성한 경우에만 URI를 반환합니다.
동영상이 있는지 확인하려면
lookupVideoMetadata
메서드를 사용하세요.
API 사용 방법
URL로 인코딩된 미국 우편 주소 또는 videoId를 전달하여 이 엔드포인트를 호출합니다.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?X-Goog-Api-Key=YOUR_API_KEY&address=POSTAL_ADDRESS "
그러면 API는 다음 세 가지 응답 중 하나를 반환합니다.
동영상이 있는 경우
lookupVideo는ACTIVE의 처리 상태와 지원되는 모든 미디어 유형의 가로 및 세로 URI, 메타데이터를 반환합니다.동영상이 시스템에 있지만 아직 완전히 렌더링되지 않은 경우
lookupVideo는PROCESSING의 처리 상태와 렌더링이 완료된 후 동영상을 가져오는 데 사용할 수 있는videoId를 반환합니다.동영상이 아직 없는 경우 API는 404 상태 코드를 반환합니다. 이 경우 새 동영상을 생성할 수 있습니다.
renderVideo
반환된 동영상 URI 사용 방법
뷰당 주소 또는 videoID당 한 번 lookupVideo 메서드를 호출합니다. 응답의 동영상 URI는 단기 URI 라고 하며 짧은 시간 후에 만료됩니다.
Google은 동영상을 자주 업데이트합니다. 따라서 고객에게 최신 콘텐츠를 표시하려면 동영상을 표시할 때마다 lookupVideo 메서드를 호출하세요.
접근성 지원 동영상
접근성을 지원하기 위해 Google은 고객에게 항공 뷰 동영상을 표시할 때 트랜스크립트 또는 동영상 설명을 추가하는 것이 좋습니다. 이렇게 하면 스크린 리더가 사용자에게 트랜스크립트 또는 설명을 알릴 수 있습니다.
예를 들어 다음과 같은 형식으로 설명을 추가합니다.
'이 동영상은 Google 지도를 통해 제공되는 ADDRESS 의 실사 항공 뷰입니다.'
주소 대신 다음과 같은 형식으로 동영상 설명을 추가할 수 있습니다.
'이 동영상은 Google 지도를 통해 제공되는 뉴욕 엠파이어 스테이트 빌딩의 실사 항공 뷰입니다.'
나중에 사용할 수 있도록 동영상 ID 저장
Aerial View API의 서비스별 약관에 따라 Aerial View API 동영상 ID에는 Google Maps Platform 서비스 약관의 3.2.3(b)항(캐싱 없음) 에 명시된 캐싱 제한사항이 적용되지 않습니다. 따라서 나중에 사용하기 위해 동영상 ID 값을 저장할 수 있습니다.
주소를 전달하는 요청 예
다음 코드 샘플은 샌프란시스코 600 Montgomery St, CA 94111에 있는 트랜스아메리카 피라미드의 항공 뷰 동영상을 요청합니다.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?X-Goog-Api-Key=YOUR_API_KEY&address=600%20Montgomery%20St%2C%20San%20Francisco%2C%20CA%2094111"
응답 예
다음 JSON 예는 lookupVideo 요청에 대한 가능한 모든 응답을 나타냅니다.
동영상 찾음
요청하는 동영상이 있는 경우 API는 요청된 동영상의 서로 다른 형식 또는 버전에 연결되는 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가 표시되며, 이 videoId를 사용하여 lookupVideo를 호출하여 동영상을 가져올 수 있습니다.
{
"state": "PROCESSING",
"metadata": {
"videoId": "u-zlVPiScvcD8BYmIVyxoF"
}
}
렌더링 프로세스는 1시간에서 몇 시간까지 걸릴 수 있습니다. 동영상이 아직 처리 중인 경우 lookupVideo를 사용하여 상태가 ACTIVE로 반환될 때까지 동영상 상태를 폴링할 수 있습니다.
폴링하려면 videoId를 전달하여 lookupVideo에 요청합니다. 렌더링은
몇 시간이 걸릴 수 있으므로
지수 백오프
를 사용하여 호출 간격을 늘리세요.
videoId를 전달하는 요청 예
lookupVideo를 호출하고 주소에 항공 뷰 동영상이 없다는 것을 알게 되면 해당 주소로 renderVideo를 호출할 수 있습니다.
renderVideo는 videoId가 포함된
VideoMetadata
객체를 반환합니다. 나중에 주소 대신 videoId를 사용하여 lookupVideo에 전달하여 동영상을 가져올 수 있습니다.
다음 코드 예는 videoId를 전달하여 lookupVideo를 호출하는 방법을 보여줍니다.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?X-Goog-Api-Key=YOUR_API_KEY&videoId=VIDEO_ID "