Portfolio

Creating an asynchronous request to process a large portfolio can be done using either the SDK or the REST endpoint.

The general workflow to create and work with a large portfolio task is:

Submit a request to create a new large portfolio task with the layer IDs to use (see below for the input format).
Upload your csv to the upload_url given in the response. This can be done via the SDK, but when done via REST For example:
```
 curl -v \
   -H 'x-goog-content-length-range: 0,524288000' \
   -H 'content-type: text/csv' \
   -X PUT \
   --upload-file /path/to/input/file.csv \
    UPLOAD_URL
```
Note

Please note the presence of the x-goog-content-length-range and content-type headers - this is required when uploading the CSV and MUST be added as it appears in the example and the HTTP method must be PUT. This is because the request is cryptographically signed (signed URLs)
Periodically poll the task status endpoint. When the task status is returned as "TASK_STATUS_COMPLETE", the results are ready to be downloaded from the download_url in the response. Results are retained for 1 week, at which point they will be deleted.

Please note, the results are compressed in a gzip file. Some web clients (like web browsers) will automatically decompress the file when downloading, but others may not. If you are using a web client that does not automatically decompress the file, you will need to decompress it manually.

See the documentation for the Python SDK for a full example using the SDK.

The Large Portfolio service can process portfolios of points or polygons.

For points, the value at each location for each layer is returned.
For polygons, a set of statistics (mean, max, min, standard deviation) for each polygon for each layer are returned.

CSV input format for points portfolio

The CSV that is uploaded should be in the format:

Latitude,Longitude
50.000,-1.000
51.000,-2.000
...

CSV output format

The result CSV will be in the format:

Latitude,Longitude,GLOBAL-1ARCSEC-....,GLOBAL-1_3ARCSEC...
50.000,-1.000,10,20
51.000,-2.000,30,40
...

On top of the latitude and longitude columns from the original CSV, there will be an additional column for each layer ID in the original task creation request.

CSV input format for portfolio polygon statistics

The service supports multiple ways of describing polygons. An input CSV can contain either a mix of "squares" and/or "circles", or it can contain only custom polygons (using WKT format).

Square

The example below describes a square in the format accepted by the service. The square is simply a bounding box around the provided coordinate (latitude/longitude). The shape parameter should be set to square. The size parameter represents half the desired length (in meters) of the sides of the square.

The uploaded CSV should be in the following format for square:

Latitude,Longitude,Shape,Size
33.748924,-133.439054,square,100
80.467420,156.131038,square,100
...

CSV output format

The result CSV will be in the following format:

Latitude,Longitude,Shape,Size,GLOBAL-1ARCSEC-..._mean,GLOBAL-1ARCSEC-..._min,GLOBAL-1ARCSEC-..._max,GLOBAL-1ARCSEC-...std_dev
33.748924,-133.439054,square,100,23,0,128,26
80.467420,156.131038,square,100,23,0,128,26
...

Circle

The input format for a circle is similar to the square format. The only difference is that shape should be set to circle and the size represents the radius of the circle in meters.

The uploaded CSV should be in the format similar to square:

Latitude,Longitude,Shape,Size
33.748924,-133.439054,circle,100
80.467420,156.131038,circle,100
...

CSV output format

The result CSV will be in the following format:

Latitude,Longitude,Shape,Size,GLOBAL-1ARCSEC-..._mean,GLOBAL-1ARCSEC-..._min,GLOBAL-1ARCSEC-..._max,GLOBAL-1ARCSEC-...std_dev
33.748924,-133.439054,circle,100,23,0,128,26
80.467420,156.131038,circle,100,23,0,128,26
...

Well Known Text (WKT)

An alternative to using the circle and square CSV format is defining WKTs for each polygon. Only POLYGON objects without inner rings are supported. The service expects these to be separated by new lines.

WKT
POLYGON ((-1.52 52.41, -1.52 52.4, -1.5 52.4, -1.5 52.41, -1.52 52.41))
POLYGON ((-1.52 52.41, -1.52 52.4, -1.5 52.4, -1.5 52.41, -1.52 52.41))
...

CSV output format

The result CSV will be in the following format:

WKT,GLOBAL-1ARCSEC-..._mean,GLOBAL-1ARCSEC-..._min,GLOBAL-1ARCSEC-..._max,GLOBAL-1ARCSEC-...std_dev
POLYGON ((-1.52 52.41, -1.52 52.4, -1.5 52.4, -1.5 52.41, -1.52 52.41))",3,0,9999,160
POLYGON ((-1.52 52.4, -1.52 52.39, -1.5 52.39, -1.5 52.4, -1.52 52.4))",3,0,9999,160
...