Introduction

FindImage will identify which discrete image has the best coverage over a requested point (lat/lon) and deliver full metadata for that image. This service also returns the metadata attribute <requested_point_wkt> which identifies the exact pixel of the requested lat/lon coordinate which is crucial for placing the discrete image properly in a viewer-like app.

Technical Details

The output metadata can be provided in three formats, xml, json or jsonp. Due to the <requested_point_wkt> attribute a DTM must be used, making this “simple” metadata query take several seconds. To make the query faster specify skip=requested_point_wkt which will bypass DTM usage.

Output Tile Specifications:

Metadata Formats (xml, json, jsonp)

Detailed information about the metadata can be found in Discrete Image Metadata.

Base URL

This service will answer to requests on following URLs:

Ordered as http REST parameters (mandatory parameters only):
https://api.gic.org/metadata/FindImage/{format}/{EPSG}/{xcoordinate}/{ycoordinate}?token={token}
Base URL with mandatory parameters defined as a mix of REST and Key Value Pairs
https://api.gic.org/metadata/FindImage/{format}/{EPSG}?xcoordinate={xcoordinate}&ycoordinate={ycoordinate}&token={token}
Base URL with all parameters defined:
https://api.gic.org/metadata/FindImage?format={format}&EPSG={EPSG}&xcoordinate={xcoordinate}&ycoordinate={ycoordinate}&orientation={orientation}&rendering={rendering}&layer={layer}&jsonpFunction={jsonpFunction}&discreteId={discreteId}&initDate={initDate}&endDate={endDate}&token={token}

Parameters

Parameter	Parameter Type	Data Type	Description	Example Format	Notes

Parameter	Parameter Type	Data Type	Description	Example Format	Notes
Mandatory:
`format`	Ordered REST (1st) - or - Key Value Pair (KVP)	String	Format of the response. `xml` - Extensible Markup Language `json` - JavaScript Object Notation `jsonp` - JavaScript Object Notation with Padding	Ordered REST: `/xml` KVP: `format=xml`	The jsonp padding can be defined with the use of the jsonFunction parameter.
`EPSG`	Ordered REST (2nd) - or - Key Value Pair	Integer	The EPSG code determines the projection of the provided coordinates.	Ordered REST: `/4326` KVP: `EPSG=4326`	More info on EPSG codes in External Resources
`xcoordinate`	Ordered REST (3rd) - or - Key Value Pair	Double	The longitudinal decimal degree coordinate for the desired point, represented by the EPSG projection defined by the EPSG parameter.	Ordered REST: `/-93.4251` KVP: `xcoordinate=-93.4251`
`ycoordinate`	Ordered REST (4th) - or - Key Value Pair	Double	The latitudinal decimal degree coordinate for the desired point, represented by the EPSG projection defined by the EPSG parameter.	Ordered REST: `/44.9186` KVP: `ycoordinate=44.9186`
`token`	Key Value Pair	Double	The token used to authenticate the requests.	`token={token}`
Optional:
`orientation`	Key Value Pair	String	The camera-axis and/or cardinal orientation of the image metadata to be returned. If undefined, metadata from all orientations will be returned. `ALL:` all orientations `NADIR:` all the Nadir orientations (NN, NS, NE, NW) `OBLIQUE:` all the oblique orientations: (N, S, E, W) Single values for specific orientations: `N, S, E, W, NN, NS, NE, NW, I`	`orientation=NADIR`
`rendering`	Key Value Pair	String	The color band rendering of the images. `all` - Default - Metadata is received from all available images `rgb` - Metadata is received only for rgb (red, green, blue) images: including both nadir and oblique. `nir` - Metadata is received only for Near-infrared images. Infrared is only available in nadir images from layers `bluesky-high`, `bluesky-ultra` and `graysky`.	`rendering=all`
`layer`	Key Value Pair	String	The desired layer. If multiple layers are to be considered, separate the layer names with commas in order of priority. `bluesky-ultra-g` (default) Urban data collected by Geomni in North America (7.5 GSD) `bluesky-ultra` Urban data collected with Osprey North America (7.5cm GSD) `bluesky-ultra-europe` Urban data collected with Osprey in Europe (7.5 GSD) `bluesky-ultra-oceania` Urban data collected with Osprey in Oceania (7.5 GSD) `bluesky-ultra-japan` Urban data collected with Osprey in Japan (7.5 GSD) `urban-r` Urban data collected with Condor (7.5 GSD) `bluesky-high` Wide area data collected with Condor in North America (15cm GSD) `bluesky-high-europe` Wide area data collected with Condor in Europe (15cm GSD) `graysky-g` Gray Sky events collected by Geomni in North America `graysky` Gray Sky events collected with Ultracam sensors in North America	`layer=bluesky-high, bluesky-ultra-europe`
`jsonpFunction`	Key Value Pair	String	The customizable name of the padding function for `format=jsonp` calls. If left undefined, the default name is VexcelFunction.	`jsonpFunction={CustomName}`
`discreteId`	Key Value Pair	String	The ID(s) for the discrete image(s) in JSON format (`[], [,], [““], [“,”]`)	`discreteId=["E_20160828_194825_2C4BC38413EC1D7"]`
`initDate`	Key Value Pair	Date String	No images collected before this date will be delivered.	`initDate=2019-01-01T00:00:01+00:00`
`endDate`	Key Value Pair	Date String	No images collected after this date will be delivered.	`endDate=2021-01-01T00:00:01+00:00`
`aoi`	Key Value Pair	String	The identifier of the Area of Interest (AOI) which contains the desired imagery. Referred to as `projectname` in metadata.	`AOI=` bluesky-ultra-g: `aoi=us-al-tuscaloosa_leica-2020` bluesky-ultra: `aoi=us-az-avondale-2021` bluesky-ultra-europe: `aoi=it-62-rome-2020` bluesky-ultra-oceania: `aoi=au-qld-sunshinecoast-2019` bluesky-ultra-japan: `aoi=jp-20-matsumoto-2022` urban-r: `aoi=us-ok-oklahomacity_rf01-2023` bluesky-high: `aoi=USUSCON2001` bluesky-high-europe: `aoi=EUEUCON2201` graysky-g: `aoi=USAZSTR1805` graysky: `aoi=us-la-neworleans-tornado-2022`
`childAOI`	Key Value Pair	String	The identifier of the child Area of Interest (AOI) which contains the desired imagery. referred to as `child_aoi` in metadata.	`ChildAOI=`
`skip`	Key Value Pair	String	Fields to be excluded in the response text, separated by commas.	`skip=requested_point_wkt`

Examples

Miami Beach, Florida - Demonstrating discreteId
https://api.gic.org/metadata/FindImage/xml/4326/-80.129779/25.785169?discreteId=2020~us-fl-miami_midas-2020~images~S_20191207_160826_54_38B700192A30854_rgb&token={token}

Table of Parameters:

Parameter	Value

Parameter	Value
`format`	`xml`
`epgs`	`4326`
`xcoordinate`	`-80.129779`
`ycoordinate`	`25.785169`
`discreteId`	`2020~us-fl-miami_midas-2020~images~S_20191207_160826_54_38B700192A30854_rgb`
`token`	`{token}`

Discrete Image Representation:
(Returned by the ExtractImages Service)

ExtractImages URL:
https://api.gic.org/images/ExtractImages/bluesky-ultra-g?mode=one&EPSG=4326&zoom=0&xcoordinate=-80.129779&ycoordinate=25.785169&imagename=2020~us-fl-miami_midas-2020~images~S_20191207_160826_54_38B700192A30854_rgb&token={token}

Metadata Output:

<?xml version="1.0" encoding="UTF-8"?>
<DiscreteImageMetadataDTO>
  <child_aoi>us-fl-miami_midas-2020</child_aoi>
  <centre_wkt>POINT(587356.5306863143 2852467.657552626)</centre_wkt>
  <childAOIPrettyname/>
  <relationPolygonInImage>0.0</relationPolygonInImage>
  <processing_toolset_version>3.3.0</processing_toolset_version>
  <layername>bluesky-ultra-g</layername>
  <bbox_wkt>POLYGON((587719.9320179333 2852127.2829637188,586995.7870055282 2852125.077425594,587054.2772570214 2852750.391178876,587656.7521565557 2852752.106143171,587719.9320179333 2852127.2829637188))</bbox_wkt>
  <flight_line_id>0412</flight_line_id>
  <AOIPrettyname/>
  <b1>0.0</b1>
  <b2>0.0</b2>
  <id>531275444</id>
  <max_zoom>0</max_zoom>
  <projectname>us-fl-miami_midas-2020</projectname>
  <k0>0.0</k0>
  <cameratechnology>MIDAS</cameratechnology>
  <k1>0.0</k1>
  <k2>0.0</k2>
  <camera_pos_y>2854160.25</camera_pos_y>
  <k3>0.0</k3>
  <original_shot_id>005_0412_00169554</original_shot_id>
  <utm_zone>17N</utm_zone>
  <omega>-0.787871</omega>
  <camera_pos_x>587351.673</camera_pos_x>
  <copyrightsentence>VEXCEL_IMAGING_INC</copyrightsentence>
  <calibration_date/>
  <capture_date>2019-12-07T16:08:26</capture_date>
  <image_id>2020~us-fl-miami_midas-2020~images~S_20191207_160826_54_38B700192A30854_rgb</image_id>
  <raster_size_width>8688.0</raster_size_width>
  <p1>0.0</p1>
  <p2>0.0</p2>
  <focal_length>130.9948</focal_length>
  <dtmfile/>
  <tile_size_x>256</tile_size_x>
  <bbox_wkt_latlon>POLYGON((-80.12509175 25.78465356,-80.13231377 25.7846769,-80.13168933 25.79031943,-80.12568047 25.79029892,-80.12509175 25.78465356))</bbox_wkt_latlon>
  <pixel_size>0.0041400000000000005</pixel_size>
  <centre_wkt_latlon>POINT(-80.12869348 25.78774858)</centre_wkt_latlon>
  <tile_size_y>256</tile_size_y>
  <min_zoom>3</min_zoom>
  <kappa>-3.138295</kappa>
  <camera_name>76752</camera_name>
  <orientation>S</orientation>
  <raster_size_height>5792.0</raster_size_height>
  <processing_date>2021-08-21T20:37:45</processing_date>
  <original_image_name>2019/38/B7/00/19/S_20191207_160826_38B700192A30854.amf</original_image_name>
  <ground_z>0.631406843662262</ground_z>
  <phi>-0.001913</phi>
  <pp0_x>0.016399999999999998</pp0_x>
  <camera_z>1695.364013671875</camera_z>
  <externalAoiId/>
  <pp0_y>0.39780000000000004</pp0_y>
  <requested_point_wkt>POINT(5659.908971752273 429.14633994536024)</requested_point_wkt>
  <gsd>0.0759344877513385</gsd>
  <aoi>us-fl-miami_midas-2020</aoi>
  <processingcenter/>
  <projectext>us-fl-miami_midas-2020</projectext>
  <relationImageInPolygon>0.0</relationImageInPolygon>
</DiscreteImageMetadataDTO>

________________________________________________________________________________________

Storm Surge Barriers - Rotterdam Netherlands - Demonstrating orientation, layer and jsonpFunction
https://api.gic.org/metadata/FindImage?format=json&epsg=4326&xcoordinate=4.164376&ycoordinate=51.954449&layer=bluesky-ultra-europe&orientation=w&jsonpFunction=SampleName&token={token}

Table of Parameters:

Parameter	Value

Parameter	Value
`format`	`json`
`epsg`	`4326`
`xcoordinate`	`4.164376`
`ycoordinate`	`51.954449`
`layer`	`bluesky-ultra-europe`
`orientation`	`w`
`jsonpFunction`	`SampleName`
`token`	`{token}`

Discrete Image Representation:
(Returned by the ExtractImages Service)

ExtractImages URL:
https://api.gic.org/images/ExtractImages/bluesky-ultra-europe?mode=one&EPSG=4326&zoom=0&xcoordinate=4.164376&ycoordinate=51.954449&imagename=2022~nl-zh-delft-2022~images~W_20220810_091516_29_6224D7B64E9185D_rgb&orientation=n&token={token}

Metadata Output:

{
child_aoi: "nl-zh-delft-2022",
centre_wkt: "POINT(4.167364069 51.95367448)",
relationPolygonInImage: 0,
processing_toolset_version: "3.3.0",
layername: "bluesky-ultra-europe",
bbox_wkt: "POLYGON((4.162018138 51.95054862,4.162029854 51.95681432,4.171309801 51.95592162,4.171224263 51.95140186,4.162018138 51.95054862))",
flight_line_id: "1",
b1: 0,
b2: 0,
id: 736450503,
max_zoom: 0,
projectname: "nl-zh-delft-2022",
k0: 0,
cameratechnology: "UltraCam_Osprey_4.1_f120",
k1: 0,
k2: 0,
camera_pos_y: 5756543.8066,
k3: 0,
original_shot_id: "58537-Lvl02-Oblique-Backward",
utm_zone: "31N",
omega: -0.014996068923602834,
camera_pos_x: 581180.6383,
copyrightsentence: "VEXCEL",
capture_date: "2022-08-10T09:15:16",
image_id: "2022~nl-zh-delft-2022~images~W_20220810_091516_29_6224D7B64E9185D_rgb",
raster_size_width: 14144,
p1: 0,
p2: 0,
focal_length: 123.38,
dtmfile: "",
tile_size_x: 256,
bbox_wkt_latlon: "POLYGON((4.162018138 51.95054862,4.162029854 51.95681432,4.171309801 51.95592162,4.171224263 51.95140186,4.162018138 51.95054862))",
pixel_size: 0.00376,
centre_wkt_latlon: "POINT(4.167364069 51.95367448)",
tile_size_y: 256,
min_zoom: 3,
kappa: 1.5906803220077002,
camera_name: "UltraCam_Osprey_4.1_f120",
orientation: "W",
raster_size_height: 10560,
processing_date: "2022-10-05T07:55:53",
original_image_name: "oblique/58537-lvl02-oblique-backward.jpg",
ground_z: -0.5402213,
phi: 0.7841676834112157,
pp0_x: 0,
camera_z: 959.3457,
requested_point_wkt: "POINT(8944.091443995552 2102.637698161486)",
pp0_y: 0,
gsd: 0.04131844465872362,
aoi: "nl-zh-delft-2022",
processingcenter: "",
projectext: "nl-zh-delft-2022",
relationImageInPolygon: 0
}

________________________________________________________________________________________

Location - Demonstrating rendering, discreteId, initDate and endDate
https://api.gic.org/metadata/FindImage/xml/4326/-80.188066/25.785280?rendering=nir&initDate=2018-01-01T00:00:01&endDate=2019-02-01T00:00:01&layer=bluesky-ultra,bluesky-high&token={token}

Table of Parameters:

Parameter	Value

Parameter	Value
`format`	`xml`
`epsg`	`4326`
`xcoordinate`	`-80.188066`
`ycoordinate`	`25.785280`
`rendering`	`nir`
`initDate`	`2018-01-01T00:00:01`
`endDate`	`2019-02-01T00:00:01`
`layer`	`layer=bluesky-ultra,bluesky-high`
`token`	`{token}`

Discrete Image Representation:
(Returned by the ExtractImages Service)

ExtractImages URL:
https://api.gic.org/images/ExtractImages/bluesky-high?mode=one&EPSG=4326&zoom=1&xcoordinate=-80.188066&ycoordinate=25.785280&imagename=2019~n25w80-us-fl-miami-2019~images~NS_20190110_180115_199_38B655588927212_irg&token={token}

Metadata Output:

<?xml version="1.0" encoding="UTF-8"?>
<DiscreteImageMetadataDTO>
  <child_aoi>n25w80-us-fl-miami-2019</child_aoi>
  <centre_wkt>POINT(-80.17781348 25.78680649)</centre_wkt>
  <childAOIPrettyname/>
  <relationPolygonInImage>0.0</relationPolygonInImage>
  <processing_toolset_version>3.3.0</processing_toolset_version>
  <layername>bluesky-high</layername>
  <bbox_wkt>POLYGON((-80.14488931 25.7822786,-80.21078851 25.78233934,-80.21076188 25.79132992,-80.14487324 25.79126109,-80.14488931 25.7822786))</bbox_wkt>
  <flight_line_id>1</flight_line_id>
  <AOIPrettyname/>
  <b1>0.0</b1>
  <b2>0.0</b2>
  <id>381675168</id>
  <max_zoom>0</max_zoom>
  <projectname>USUSCON1901</projectname>
  <k0>0.0</k0>
  <cameratechnology>UltraCam_Condor_Mark_1_f100</cameratechnology>
  <k1>0.0</k1>
  <k2>0.0</k2>
  <camera_pos_y>2852330.2894</camera_pos_y>
  <k3>0.0</k3>
  <original_shot_id>947-Lvl02-RGBI</original_shot_id>
  <utm_zone>17N</utm_zone>
  <omega>3.138103675262016E-4</omega>
  <camera_pos_x>582436.7291</camera_pos_x>
  <copyrightsentence>VEXCEL_IMAGING_INC</copyrightsentence>
  <calibration_date>2019-09-09T00:00:00</calibration_date>
  <capture_date>2019-01-10T18:01:15</capture_date>
  <image_id>2019~n25w80-us-fl-miami-2019~images~NS_20190110_180115_199_38B655588927212_irg</image_id>
  <raster_size_width>33192.0</raster_size_width>
  <p1>0.0</p1>
  <p2>0.0</p2>
  <focal_length>100.45</focal_length>
  <dtmfile/>
  <tile_size_x>256</tile_size_x>
  <bbox_wkt_latlon>POLYGON((-80.14488931 25.7822786,-80.21078851 25.78233934,-80.21076188 25.79132992,-80.14487324 25.79126109,-80.14488931 25.7822786))</bbox_wkt_latlon>
  <pixel_size>0.0046</pixel_size>
  <centre_wkt_latlon>POINT(-80.17781348 25.78680649)</centre_wkt_latlon>
  <tile_size_y>256</tile_size_y>
  <min_zoom>7</min_zoom>
  <kappa>-3.1364596159265257</kappa>
  <camera_name>UltraCam_Condor_Mark_1_f100</camera_name>
  <orientation>I</orientation>
  <raster_size_height>5000.0</raster_size_height>
  <processing_date>2021-07-09T15:15:44</processing_date>
  <original_image_name>nadir/947-lvl02-rgbi.tif</original_image_name>
  <ground_z>1.33496726</ground_z>
  <phi>0.0010348056625552212</phi>
  <pp0_x>0.0</pp0_x>
  <camera_z>4348.14941</camera_z>
  <externalAoiId/>
  <pp0_y>-0.0</pp0_y>
  <requested_point_wkt>POINT(21761.815287028323 1644.7979706314977)</requested_point_wkt>
  <gsd>0.19905781127272074</gsd>
  <aoi>USUSCON1901</aoi>
  <processingcenter/>
  <projectext>n25w80-us-fl-miami-2019</projectext>
  <relationImageInPolygon>0.0</relationImageInPolygon>
</DiscreteImageMetadataDTO>

External Resources

EPSG Codes: https://en.wikipedia.org/wiki/EPSG_Geodetic_Parameter_Dataset
Decimal Degrees: https://en.wikipedia.org/wiki/Decimal_degrees

Vexcel API Documentation

FindImage Service - v1.4

Introduction

Technical Details

Base URL

Parameters

Examples

See Also

External Resources