Support will officially be ending for API 1.0 October 31st, 2025 please make sure to start migrating over to API 2.0 - a migration document can be found here. As of March 1st, 2025 no updates will be made to API 1.0

Introduction

The ExtractImages service will take a point or polygon and return one or more discrete RGB images, depending on the parameters of the request. This service retrieves Nadir and Oblique Images from both the Geomni and Vexcel libraries covering both Blue Sky and Gray Sky collections. Due to the broad collection specifications (multi-sensor, multi-library, multi-camera-orientation, etc. ) this is a diverse compilation of data with an enormous list of potential uses, including:

Aerial Survey
Disaster Assessment
Engineering/Construction
Navigation/network planning
Landscape Change Detection

Use a service such as ImageLayerCoverage Service, FindImagesInPoint Service or FindImagesInPolygon Service to query for image coverage.

Technical Details

The ExtractImages service is accessed by specifying a point (latitude and longitude) or polygon (well-known-text). Depending on parameters, this service will return the whole image or a portion of the image. In addition to the standard GET request, this service offers the ability to overlay drawing elements (vector and text data) on imagery using POST calls. While NIR images may be returned if mode=all or mode=best; this is a backwards compatible feature and it is recommended that the ExtractNIRImages service be used if NIR images are expressly desired.

Output Image Specifications:

8-bit depth
3-band (RGB)
7.5 or 20 cm centimeter resolution (layer dependent)
Nadir and Oblique imagery available
Blue Sky and Gray Sky imagery available
Jpeg image format
Output Format: Jpeg images in a compressed folder
- Folder Name: {layer parameter}.zip
- Image Name: variable, dependent on layer
- Metadata in a variety of formats with many attributes

Base URL

The ExtractImages service responds to the following base URL: https://api.gic.org/images/ExtractImages/{layer}/

Base URL with only mandatory parameters:
- Lat/Lon Coordinate Point
  https://api.gic.org/images/ExtractImages/{layer}?mode={mode}&zoom={zoom}&EPSG={EPSG}&token={token}&xcoordinate={xcoordinate}&ycoordinate={ycoordinate}
- wkt Polygon Area
  https://api.gic.org/images/ExtractImages/{layer}?mode={mode}&zoom={zoom}&EPSG={EPSG}&token={token}&wkt={wkt}
Base URLs with all parameters defined:
- Lat/Lon Coordinate Point
  https://api.gic.org/images/ExtractImages/{layer}?mode={mode}&zoom={zoom}&EPSG={EPSG}&token={token}&xcoordinate={xcoordinate}&ycoordinate={ycoordinate}&width={width}&height={height}&imagename={imagename}&projCode={projCode}&childAOI={childAOI}&initDate={initDate}&endDate={endDate}&nadirRotatedNorth={nadirRotatedNorth}&orientation={orientation}&metadata={metadata}&excludeJGWfiles={excludeJGWfiles}&drawing={drawing}&logo={logo}&demPriority={demPriority}
- wkt Polygon Area
  https://api.gic.org/images/ExtractImages/{layer}?mode={mode}&zoom={zoom}&EPSG={EPSG}&token={token}&wkt={wkt}&crop={crop}&imagename={imagename}&projCode={projCode}&childAOI={childAOI}&initDate={initDate}&endDate={endDate}&nadirRotatedNorth={nadirRotatedNorth}&orientation={orientation}&metadata={metadata}&excludeJGWfiles={excludeJGWfiles}&drawing={drawing}&logo={logo}&demPriority={demPriority}

Parameters

Parameter	Parameter Type	Data Type	Description	Format Example	Notes

Parameter	Parameter Type	Data Type	Description	Format Example	Notes
Mandatory Parameters:
`layer`	Ordered REST	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/`	The `layer` parameter must be defined within the URL as an ordered REST parameter rather than a Key-Value pair. This is the only layer that must be defined in this manner.
`mode`	Key-Value-Pair	string	Indicates the work mode of the service request. `all` All the available images in the area from a single camera `orientation`. `best` One image from each camera orientation, each with best coverage over the input area. See the note to the right for more info on best coverage. `one` Only the image as defined in `imagename` parameter. If `imagename` is undefined, `mode=best` will be used instead.	`mode=all`	If you specify `all` you must include a single-value `orientation` parameter. Definition of `mode=best`: Images are defined as `best` depending on the method of defining an input area: - lat/lon - The image with a center point closest to the input coordinate is considered `best` - wkt polygon - The image that covers the most of the input polygon is considered `best` In both cases, if there are multiple images which meet the `best` criteria, the most recent image will be returned.
`zoom`	Key-Value-Pair	Integer	The zoom level of the returned images. 0 = Full Resolution 1 = 1/4 Resolution 2 = 1/16 Resolution 3 = 1/64 Resolution - Maximum zoom	`zoom=2`
`EPSG`	Key-Value-Pair	Integer	The EPSG code determines the projection of the provided coordinates or polygon.	`EPSG=4326`	More info on EPSG codes in External Resources
`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. Can either be present as URL parameter or cookie with the same name.
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 desired point, 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 desired point, represented by the EPSG projection defined by the `EPSG` parameter.	`ycoordinate=44.9186`
Polygon
`wkt`	Key-Value-Pair	string	The “well-known text” field is used to define a 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
`width` (will only work with a pair of Lat/Lon coordinates)	Key-Value-Pair	Integer	The width (in pixels) defining the east/west extent of a rectangle centered on the lat/lon coordinate point. Images intersecting the rectangle will be returned, cropped by the rectangle extent. If not specified, full image(s) intersecting the lat/lon coordinate point will be retrieved.	`width=400`	The `width` parameter is only available for requests using `xcoordinate`/`ycoordinates`.
`height` (will only work with a pair of Lat/Lon coordinates)	Key-Value-Pair	Integer	The height (in pixels) defining the north/south extent of a rectangle centered on the lat/lon coordinate point. Images intersecting the rectangle will be returned, cropped by the rectangle extent. If not specified, full image(s) intersecting the lat/lon coordinate point will be retrieved.	`height=400`	The `height` parameter is only available for requests using `xcoordinate`/`ycoordinates`.
`crop` (will only work with a wkt polygon)	Key-Value-Pair	string	The method with which to crop the returned images based on the input `wkt` parameter. `crop`- Default value if `wkt` is provided - Crops the image(s) to the minimum bounding rectangle of the wkt polygon values. `exact` - Crops the image(s) to the exact shape of the wkt polygon. `full` - Default value if no `wkt` is provided - Whole image(s) which intersect the wkt polygon will be returned. wkt polygon:	`crop=boundingBox`	The `crop` parameter is only available for requests using the `wkt` parameter
`imagename`	Key-Value-Pair	string	Only the image referred to by this parameter will be downloaded.	`imagename=2018~n30w88-n30w89-us-al-mobile-2018~nadir~200531-lvl02-rgbi`	The `imagename` parameter is only available if `mode` is set to `one` `imagename` can be obtained through findImage or similar services.
`projCode`	Key-Value-Pair	string	The AOI identifier or project name that contains the delivered images.	`projCode=us-la-marrero-2019` 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`	`projcode`can be obtained through findImage or similar services.
`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 `projCode` 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. `jpeg` - default `tiff` - Georeferenced tiff	`format=jpeg`
`initDate`	Key-Value-Pair	String	No images collected before this date will be delivered.	`initDate=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")
`nadirRotatedNorth`	Key-Value-Pair	string	Determines the rotation of the image (Nadir images only): `no` - Default value - Rotated to orientation of collection `yes` - North-orientated.	`nadirRotatedNorth=yes`	By default, images are returned with forward direction of collection up rather than north up. Generally most users will want to set `nadirRotatedNorth=yes`, especially when `orientation=nadir`.
`orientation`	Key-Value-Pair	string	The camera-axis and/or cardinal orientation of the images to be delivered. `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`	Required when `mode=one`
`metadata`	Key-Value-Pair	string	The type of metadata schema to be delivered along with the images. Metadata and images are delivered in the same zip file. `none` - default `xm8` - `csv` - `json` -	`metadata=json`	ExtractImages Service - v1.4#Metadata-Formats%3ASee Discrete Images Metadata for more information on the format and type of metadata available.
`excludeJGWfiles`	Key-Value-Pair	boolean	The JGW file contains the information needed to georeference a JPEG image. JGW files are only available when area is defined by `wkt`. To exclude all JGW files, set `excludeJGWfiles` = `true`	`excludeJGWfiles=true`	JGW files are not available when area is defined by x/y coordinates. JGW files are not delivered when `mode=one`; this allows for the returned image to remain unzipped. To receive a JGW file when `mode=one`, `metadata` must be requested (results will be returned in a zipped folder).
`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`
`drawing`	Key-Value-Pair	string	The signal to be drawn in the delivered images as a marker of the requested x/y coordinate point (or `wkt` center point). `none` - Default value - No signal drawing will be made on the image(s) `cross` - A yellow cross signaling the requested point will be made on the image(s).	`drawing=cross`	The location of the marker will be identified using our underlying DSM layer unless another dem is selected with the `demPriority` parameter.

ExtractImages Service - v1.4

Introduction

Technical Details

Base URL

Parameters