FindImage Service - v1.4
- Scott Jonker
- Clara Baker
Analytics
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 |
|---|---|---|---|---|---|
Mandatory: | |||||
| Ordered REST (1st) - or - Key Value Pair (KVP) | String
| Format of the response.
| Ordered REST: | The jsonp padding can be defined with the use of the jsonFunction parameter. |
| Ordered REST (2nd) - or - Key Value Pair | Integer | The EPSG code determines the projection of the provided coordinates. | Ordered REST: | More info on EPSG codes in External Resources |
| 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: | More info on Decimal Degrees in External Resources |
| 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: KVP: |
|
| Key Value Pair | Double | The token used to authenticate the requests. |
| Use the Authentication Token Service to receive a token. A token will temporarily be stored in cache and may be omitted on subsequent calls. |
Optional: | |||||
| 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.
Single values for specific orientations: | |
|
| Key Value Pair | String | The color band rendering of the images.
|
|
|
| Key Value Pair | String | The desired layer. If multiple layers are to be considered, separate the layer names with commas in order of priority.
Urban data collected with Osprey in Japan (7.5 GSD)
Urban data collected with Condor (7.5 GSD)
|
| It is possible that images from different layers may have the same file name. The imagery/content will be different. If this parameter is omitted, then this service will only look at the default layer, |
| Key Value Pair | String | The customizable name of the padding function for |
| This parameter is only available if format=jsonp |
| Key Value Pair | String | The ID(s) for the discrete image(s) in JSON format ( |
| Use a service like FindImagesInPoint Service or FindImagesInPolygon Service to identify |
| Key Value Pair | Date String | No images collected before this date will be delivered. |
| Format: ISO 8601 (" |
| Key Value Pair | Date String | No images collected after this date will be delivered. |
| Format: ISO 8601 ("yyyy-MM-dd'T'HH:mm:ss") |
| Key Value Pair | String | The identifier of the Area of Interest (AOI) which contains the desired imagery. Referred to as |
bluesky-ultra-g: bluesky-ultra: bluesky-ultra-europe: bluesky-ultra-oceania: bluesky-ultra-japan: urban-r: bluesky-high: bluesky-high-europe: graysky-g: graysky: | What constitutes an AOI: Urban (bluesky-ultra): A small region covering all or parts of a metropolitan area. Wide Area (bluesky-high): A large region over a single year (e.g. USA 2020) Graysky: A singular event ( e.g. IDA 2021) |
| Key Value Pair | String | The identifier of the child Area of Interest (AOI) which contains the desired imagery. referred to as |
bluesky-ultra-g: bluesky-ultra: bluesky-ultra-europe: bluesky-ultra-oceania: bluesky-ultra-japan: urban-r: bluesky-high: bluesky-high-europe: graysky-g: graysky: | What constitutes a childAOI: Urban (bluesky-ultra): The same region as the AOI (1:1 relationship) Wide Area (bluesky-high): A subset of the Wide area AOI (often a single one degree cell) Graysky: A singular flight session within the Graysky event |
| Key Value Pair | String | Fields to be excluded in the response text, separated by commas.
|
| If this parameter is not included, all metadata objects will be returned. By using |
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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 jsonpFunctionhttps://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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 endDatehttps://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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
Note, the following resources are external to Vexcel and may change without prior notice.
EPSG Codes: EPSG Geodetic Parameter Dataset
Decimal Degrees: Decimal degrees
Related content
Need help? Create a support ticket | support@vexcelgroup.com