Introduction

This service returns a piece of imagery as a JPG or PNG, cut from the seamless orthomosaic. The same imagery you can access via GetOrthoImageTiles is used to create the returned image. ExtractOrthoImages saves you the work of making multiple API calls to GetOrthoImageTiles for individual tiles, stitching them together into a large bitmap, and cropping it to your spec. With a single API call you can get back a static map image matching your specification.

Note: the maximum size for a returned image is 67,108,864 pixels or the equivalent of 1,024 individual tiles. If your request results in an image exceeding these limits, an error is returned.

Technical Details

You can use the OrthoCoverage service to determine where ortho coverage exists. This allows you to know if a call to ExtractOrthoImages will succeed or fail based on image availability.

USE CASES

All use cases will ensure that imagery will not exceed either 67,108,864 pixels (e.g., 4096 x 16384) or 1,024 tiles.

xcoordinate + ycoordinate + zoom + width + height: This is the most common use of the service. Here you pass in a coordinate where the image will be centered and a standard zoom level. You also pass in the width and height in Pixels of the image you want returned.
wkt: Here you pass a polygon in the WKT parameter that you want covered by the returned image. The service will calculate the deepest zoom level that covers the polygon with less than the maximum number of tiles (1,024). The resulting bitmap will be fit to the minimum bounding rectangle (or MBR) for the polygon that was passed in the WKT parameter. Note that the Pixel dimensions of the resulting image are also determined by the service and cannot be specified.
wkt + zoom: This is very similar to the previous case, but instead of the system selecting the optimal Zoom level, you specify it with the Zoom parameter. This allows you to scale the image (shown below under examples).

Output Tile Specifications:

8-bit depth
3-band (RGB or NIR)
7.5 or 20 cm centimeter resolution (layer dependent)
Image format: JPEG or PNG
Blue Sky and Gray Sky imagery available
Maximum size: 67,108,864 pixels or 1,024 tiles

Base URL

This service will answer to requests on following URLs:

Lat/Lon Coordinate Point
https://api.gic.org/images/ExtractOrthoImages?layer={layer}&epsg={epsg}&xcoordinate={xcoordinate}&ycoordinate={ycoordinate}&width={width}&height={height}&zoom={zoom}&token={token}
wkt Polygon Area
https://api.gic.org/images/ExtractOrthoImages?layer={layer}&epsg={epsg}&wkt={wkt}&token={token}

Parameters

Parameter	Parameter Type	Data Type	Description	Example Format	Notes

Parameter	Parameter Type	Data Type	Description	Example Format	Notes
Mandatory:
`layer`	Ordered REST 1st or key-value-pair	String	Layer of the requested image. `bluesky-ultra-g` Urban data collected by Geomni (7.5 GSD) `bluesky-ultra` Urban data collected with Osprey (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 (15cm GSD) `bluesky-high-europe` Wide area data collected with Condor in Europe (15cm GSD) `graysky-g` Gray Sky events collected by Geomni `graysky` Gray Sky events collected with Ultracam sensors	`/bluesky-ultra-g/`
`EPSG`	Key-Value-Pair	Integer	ESPG code that determines the projection of the coordinates provided. A valid example would be 4326 for geographical latitude-longitude coordinates.	`EPSG=4326`
`token`	Key-Value-Pair	String	Authentication token received from Login service. Specific to each individual user.	`token={token}`	Use the Authenticate Service to receive a token.
Mandatory - Method of defining area: Lat/Lon Coordinates or Polygon. Only one method can be used per URL call.
Lat/Lon Coordinates
`xcoordinate`	Key-Value-Pair	Double	The longitudinal decimal degree coordinate for the center of the desired image, represented by the EPSG projection defined by the `EPSG` parameter.	`xcoordinate=-93.4251`	More info on Decimal Degrees in External Resources
`ycoordinate`	Key-Value-Pair	Double	The latitudinal decimal degree coordinate for the center of the desired image, represented by the EPSG projection defined by the `EPSG` parameter.	`ycoordinate=44.9186`
`width`	Key-Value-Pair	Integer	the width of the returned image in pixels.	`width=600`	The `width` parameter is only available for requests using `xcoordinate` / `ycoordinates`.
`height`	Key-Value-Pair	Integer	the height of the returned image in pixels.	`height=400`	The `height` parameter is only available for requests using `xcoordinate` / `ycoordinates`.
`zoom`	Key-Value-Pair	Integer	standard mercator tile zoom level from 1 to 21.	`zoom=20`	The `zoom` parameter is mandatory for requests using `xcoordinate` / `ycoordinates`, optional for requests using `wkt`.
Polygon
`wkt`	Key-Value-Pair	String	The “well-known text” field is used to define a point, polygon or multi-polygon around the desired area.	`wkt=POLYGON((-93.41947148592193 44.91507523063691,-93.4185112550946 44.91507523063691,-93.4185112550946 44.91431925758581,-93.41947148592193 44.91431925758581,-93.41947148592193 44.91507523063691))`	More info on well-known text (wkt) in External Resources
Optional Parameters:
`zoom`	Key-Value-Pair	Integer	standard mercator tile zoom level from 1 to 21.	`zoom=20`	The `zoom` parameter is mandatory for requests using `xcoordinate` / `ycoordinates`, optional for requests using `wkt`. The max zoom for `bluesky-high` layers is `20`, for `bluesky-ultra` layers is `21`. Check OrthoCoverage Service which will give you the AOI Max Zoom in the metadata.
`year`	Key-Value-Pair	String	the 4-digit year of the collection to be used in creating the image. if there are more than 1 collections in the year, the most recent collection is used.	`year=2021`	The `year` parameter queries against the `max_capture_date` as found in the coverage metadata.
`crop`	Key-Value-Pair	String	The method with which to crop the returned images based on the input `wkt` parameter. `crop`- Default - Clips the image(s) to the minimum bounding rectangle of the `wkt` polygon. `exact` - Clips the image(s) to the exact shape of the `wkt` polygon.	`crop=crop`	The `crop` parameter is only available for requests using the `wkt` parameter
`AOI`	Key-Value-Pair	String	The identifier of the Area of Interest (AOI) which contains the desired imagery.	`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=EUEUCON2001` graysky-g: `aoi=USMSCOL1902` graysky: `aoi=us-la-neworleans-tornado-2022`	The available `AOI`(s) for a point or polygon can be determined using the OrthoCoverage service.
`ChildAOI`	Key-Value-Pair	String	The identifier of the child Area of Interest (AOI) which contains the desired imagery. This parameter can only be used in combination with the `AOI` parameter in cases where the AOI contains several smaller collection regions; for many Blue Sky AOIs there is no child AOI. This parameter can be especially useful for Gray Sky events.	`ChildAOI=` bluesky-ultra-g: `ChildAOI=us-al-tuscaloosa_leica-2020` bluesky-ultra: `ChildAOI=us-az-avondale-2021` bluesky-ultra-europe: `ChildAOI=it-62-rome-2020` bluesky-ultra-oceania: `ChildAOI=au-qld-sunshinecoast-2019` bluesky-ultra-japan: `ChildAOI=jp-20-matsumoto-2022` urban-r: `ChildAOI=us-ok-oklahomacity_rf01-2023` bluesky-high: `ChildAOI=n33w87-us-al-tuscaloosa-2019` bluesky-high-europe: `ChildAOI=n41e13-it-lt-aprilia-2020` graysky-g: `ChildAOI=190226/USMSCOLDMC` graysky: `ChildAOI=graydata-363`	The available `ChildAOI`(s) for a point or polygon can be determined using the OrthoCoverage service.
`format`	Key-Value-Pair	String	The image file format. `png` - Default for layers bluesky-high and bluesky-ultra. Capable of returning a transparent background where imagery does not exist. `jpeg` - Default for layer bluesky-ultra-g `tiff` - Georeferenced tiff	`format=image/png`	To receive an image with transparent background, use format=image/png.
`dst_height`	Key Value Pair	Integer	The combination of `dst_height` and `dst_width` is used to define the size and aspect ratio of a destination frame. The input geometry will be centered within the destination frame with additional imagery extending either vertically or horizontally to fill the destination frame if necessary.	`dst_height=600`
`dst_width`	Key Value Pair	Integer	The combination of `dst_height` and `dst_width` is used to define the size and aspect ratio of a destination frame. The input geometry will be centered within the destination frame with additional imagery extending either vertically or horizontally to fill the destination frame if necessary.	`dst_width=800`
`startDate` Alias: `initDate`	Key-Value-Pair	String	No images taken before this date will be delivered.	`startDate=2019-01-01T00:00:01+00:00`	Format: ISO 8601 ("yyyy-MM-dd'T'HH:mm:ss")
`endDate`	Key-Value-Pair	String	No images collected after this date will be delivered.	`endDate=2021-01-01T00:00:01+00:00`	Format: ISO 8601 ("yyyy-MM-dd'T'HH:mm:ss")
`returnTransparent`	Key Value Pair	Boolean	The flag that determines what to return along with a “404 - Imagery not found” response. `True` - A completely transparent .png file. `False` - `message: “Information not found”`	`returnTransparent=True`	This parameter is only available when `format=png`. If any imagery is available within the tile, the non-imagery pixels will be either black (`format=jpeg`) or transparent (`format=png`).
`rotatedNorth`	Key Value Pair	string	Determines the rotation of the image: `no` - default - Rotated to orientation of collection `yes` - North-orientated.	`rotatedNorth=yes`
`renderingRule`	Key-Value-Pair	String	The color band rendering of the tiles. `rgb` - Default - Red, green and blue bands `nir` - Near-infrared band (partially unavailable for `bluesky-ultra-g` or `graysky-g`)	`renderingRule=rgb`	`nir` is not available for all imagery in the `bluesky-ultra-g` or `graysky-g` layers due to those layers having imagery from multiple collection sensors, of which only one collected NIR imagery.
`apply_coverage_mask`	Key Value Pair	String	Applies mask for transparency when true, removes black pixels when false `true` `false`	`apply_coverage_mask=false`

Optional - Drawing Elements (POST Request)

The ExtractOrthoImages service allows for the inclusion of custom drawing elements using a POST request. A POST request takes typical REST parameters (defined within the URL) but adds JSON elements in the body of the POST call to define the drawing elements.

Drawing Element Parameters

drawingPolygon - The polygon to be draw in WKT format (The EPSG has to be the same EPSG that is in the head of the petition)
lineWidth - The width for the polygon’s exterior line
outlineColor - The color for the polygon’s exterior line (RGB format)
fillColor - The color for the polygon’s fill
drawingPointList - An object list of point(s) and associated label(s)
- point - The point coordinates in latitude and longitude (decimal degrees).
- label - The custom label for each point.
fontSize - Font point size for labels
fontColor - Font color for labels (RGB color)
fontType - Font typeface (Options: Monospaced, SansSerif or Serif)

JSON format:

{
  "drawingPolygon": "[polygon wkt]",
  "lineWidth": "[linewidth]",
  "outlineColor": "[rgb]",
  "fillColor": "[rgb]",
  "drawingPointList": [
    {
      "point": "[point wkt]",
      "label": "[custom text]"
    },
    {
      "point": "[point wkt]",
      "label": "[custom text]"
    }
  ],
  "fontSize": "[font point size]",
  "fontColor": "[rgb]",
  "fontType": "[font typeface]"
}

REST URL:
https://api.gic.org/images/ExtractOrthoImages?layer=bluesky-ultra&wkt=POLYGON((-81.564125 28.375218,-81.560114 28.374481,-81.562096 28.372312,-81.563675 28.372653,-81.564125 28.375218))&EPSG=4326&token={token}

POST body data:

{
  "drawingPolygon": "POLYGON ((-81.563318 28.373955, -81.563543 28.373962, -81.563811 28.374158,-81.563940 28.374434, -81.563897 28.374666, -81.563709 28.374859, -81.563476 28.374956, -81.563269  28.374989, -81.563044 28.374932,-81.562878 28.374826,-81.562744 28.374564, -81.562754 28.374319,-81.562835 28.374191,-81.562575 28.374213, -81.562551 28.374205, -81.562288 28.374135, -81.562052 28.374024,-81.562030 28.374198, -81.562017 28.374201, -81.561883 28.374423, -81.561609 28.374538, -81.561365 28.374536, -81.561097 28.374423, -81.560906 28.374182, -81.560893 28.373962,-81.560885 28.373955, -81.560947 28.373769, -81.560952 28.373774, -81.561247 28.373568, -81.561250 28.373556, -81.561534 28.373538, -81.561714 28.373556, -81.561714 28.373174, -81.561893 28.372884, -81.562309 28.372605, -81.562714 28.372542, -81.563015 28.372598, -81.563323 28.372801, -81.563312 28.372806, -81.563530 28.373073, -81.563605 28.373438, -81.563602 28.373443, -81.563530 28.373717, -81.563444 28.373840, -81.563318 28.373955))",
  "lineWidth": "3",
  "outlineColor": "rgb(0,0,0)",
  "fillColor": "rgb(254,179,179)",
  "drawingPointList": [
    {
      "point": "POINT(-81.562738 28.373370)",
      "label": "Mickey Mouse"
    }
  ],
  "fontSize": "50",
  "fontColor": "rgb(0,0,0)",
  "fontType": "Arial"
}

Response:

Parameters and Body as seen in Talend API Tester (3rd party API testing webapp):

Examples

These examples cover the three ways to specify an image as discussed under the Technical Details section.

xcoordinate + ycoordinate + zoom + width + height

The Atomium - Brussels, Belgium - Demonstrating the ycoordinate , xcoordinate ,layer , width and height parameters

REST URL:

https://api.gic.org/images/ExtractOrthoImages/bluesky-high-europe?ycoordinate=50.894916&xcoordinate=4.340991&zoom=17&width=600&height=400&EPSG=4326&token={token}

Parameter	Value

Parameter	Value
`layer`	`bluesky-high-europe`
`ycoordinate`	`50.894916`
`xcoordinate`	`4.340991`
`zoom`	`17`
`width`	`600`
`height`	`400`
`EPSG`	`4326`
`token`	`{token}`

Image:

________________________________________________________________________________________

2. wkt

Fort McHenry National Monument and Historic Shrine - Baltimore, MD - Demonstrating the epsg , wkt,zoom, format, AOI and renderingRule parameters

REST URL:

https://api.gic.org/images/ExtractOrthoImages?layer=bluesky-ultra&epsg=4326&wkt=POLYGON((-76.580924 39.263944, -76.578685 39.263938, -76.578682 39.262136, -76.580924 39.262134, -76.580924 39.263944))&format=image/png&AOI=us-md-baltimore-2021&renderingRule=nir&token={token}

Parameter	Value

Parameter	Value
`layer`	`bluesky-ultra`
`epsg`	`4326`
`wkt`	`POLYGON((-76.580924 39.263944, -76.578685 39.263938, -76.578682 39.262136, -76.580924 39.262134, -76.580924 39.263944))`
`format`	`image/png`
`AOI`	`us-md-baltimore-2021`
`renderingRule`	`nir`
`token`	`{token}`

Image:

________________________________________________________________________________________

3. wkt + zoom

Shrine of Remembrance - Melbourne, Australia - Demonstrating the zoom , startDate, and endDate parameters

REST URL:

https://api.gic.org/images/ExtractOrthoImages?zoom=19&layer=bluesky-ultra-oceania&epsg=4326&wkt=POLYGON ((144.972431 -37.830084, 144.973944 -37.829724, 144.974269 -37.830955, 144.973075 -37.831252, 144.972431 -37.830084))&startDate=2021-02-09T00:00:01+00:00&endDate=2021-03-16T23:59:59+00:00&token={token}

Parameter	Value

Parameter	Value
`layer`	`bluesky-ultra-oceania`
`epsg`	`4326`
`wkt`	`POLYGON ((144.972431 -37.830084, 144.973944 -37.829724, 144.974269 -37.830955, 144.973075 -37.831252, 144.972431 -37.830084))`
`zoom`	`19`
`startDate`	`2021-02-09T00:00:01+00:00`
`endDate`	`2021-03-16T23:59:59+00:00`
`token`	`{token}`

Image:

External Resources

Note, the following resources are external to Vexcel and may change without prior notice.

EPSG Codes: EPSG Geodetic Parameter Dataset
Well-known text (wkt): Well-known text representation of geometry
Decimal Degrees: Decimal degrees

Vexcel API Documentation

ExtractOrthoImages - v1.4

Analytics

Introduction

Technical Details

Base URL

Parameters

Optional - Drawing Elements (POST Request)

Examples

See Also

External Resources

Related content