gRPC
This page provides a description of the Fathom gRPC API. This should only ever be interacted with via a Fathom client SDK, but is here for completion.
fathom/api/v2/common.proto
Messages
Metadata for requests made to the API.
| Field |
Type |
Description |
| project_id |
string |
In some cases you may require Fathom API queries to be billed as part of an internal project. The project ID is stored in Fathom's usage database and will be used to itemise usage for billing purposes. |
|
|
|
fathom/api/v2/fathom.proto
FathomService
FathomService defines the externally facing API for querying Fathom data.
GetPolygonData
rpc GetPolygonData(GetPolygonDataRequest)
GetPolygonDataResponse
Returns data in tiff format for the given polygon from supplied layers.
GetPointsData
rpc GetPointsData(GetPointsDataRequest)
GetPointsDataResponse
Returns data for given points (locations) from supplied layers.
GetGeoJSONPointsData
rpc GetGeoJSONPointsData(GetGeoJSONPointsDataRequest)
GetPointsDataResponse
Returns data for the supplied layers using points parsed from the given GeoJSON.
Returns an error if any geometries in the request are not Point or MultiPoint.
GetGeoJSONPolygonData
rpc GetGeoJSONPolygonData(GetGeoJSONPolygonDataRequest)
GetPolygonDataResponse
Returns data for the supplied layers using a polygon parsed from the given GeoJSON.
Returns an error if there is not exactly one polygon geometry in the request.
GetGeoJSONPolygonStats
rpc GetGeoJSONPolygonStats(GetGeoJSONPolygonStatsRequest)
GetPolygonStatsResponse
Returns stats for the supplied layers using a polygon parsed from the given GeoJSON.
Returns an error if there is not exactly one polygon geometry in the request.
GetPolygonStats
rpc GetPolygonStats(GetPolygonStatsRequest)
GetPolygonStatsResponse
Returns statistics data retrieved from making geo-query to given polygon and from the layers.
GetShapePolygonStats
rpc GetShapePolygonStats(GetShapePolygonStatsRequest)
GetShapePolygonStatsResponse
Returns statistics for the supplied layers using the primitive polygon shape described in the request.
GetWKTPolygonStats
rpc GetWKTPolygonStats(GetWKTPolygonStatsRequest)
GetWKTPolygonStatsResponse
Returns statistics for the supplied layers using the wkt polygon described in the request.
CreateAccessToken
rpc CreateAccessToken(CreateAccessTokenRequest)
CreateAccessTokenResponse
Returns a token used to access the API.
GetLargePolygonData
rpc GetLargePolygonData(GetLargePolygonDataRequest)
GetLargePolygonDataResponse
Returns data as a link to a compressed archive of 1 tif per layer for the given polygon from supplied layers.
Can only accept a maximum of 40 layers.
Messages
CreateAccessTokenRequest
| Field |
Type |
Description |
| client_id |
string |
Client ID to identify the user. Required. |
| client_secret |
string |
Client Secret used with the provided Client ID. Required. |
|
|
|
CreateAccessTokenResponse
| Field |
Type |
Description |
| access_token |
string |
JWT to access the API. |
| expire_secs |
uint64 |
Seconds until this token expires |
|
|
|
GetGeoJSONPointsDataRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| points_geojson |
map GetGeoJSONPointsDataRequest.PointsGeojsonEntry |
none |
|
|
|
GetGeoJSONPointsDataRequest.PointsGeojsonEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
google.protobuf.Value |
none |
|
|
|
GetGeoJSONPolygonDataRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| polygon_geojson |
map GetGeoJSONPolygonDataRequest.PolygonGeojsonEntry |
none |
|
|
|
GetGeoJSONPolygonDataRequest.PolygonGeojsonEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
google.protobuf.Value |
none |
|
|
|
GetGeoJSONPolygonStatsRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| polygon_geojson |
map GetGeoJSONPolygonStatsRequest.PolygonGeojsonEntry |
none |
|
|
|
GetGeoJSONPolygonStatsRequest.PolygonGeojsonEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
google.protobuf.Value |
none |
|
|
|
GetLargePolygonDataRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| polygon |
Polygon |
none |
|
|
|
GetLargePolygonDataResponse
| Field |
Type |
Description |
| download_url |
string |
URL to download results of the request query. |
|
|
|
GetPointsDataRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| points |
repeated Point |
none |
|
|
|
GetPointsDataResponse
| Field |
Type |
Description |
| results |
map GetPointsDataResponse.ResultsEntry |
Map of layer ID to the points result for that layer |
|
|
|
GetPointsDataResponse.ResultsEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
PointResult |
none |
|
|
|
GetPolygonDataRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| polygon |
Polygon |
none |
|
|
|
GetPolygonDataResponse
| Field |
Type |
Description |
| results |
map GetPolygonDataResponse.ResultsEntry |
Map of layer ID to the polygon result for that layer |
|
|
|
GetPolygonDataResponse.ResultsEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
PolygonResult |
none |
|
|
|
GetPolygonStatsRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| polygon |
Polygon |
none |
|
|
|
GetPolygonStatsResponse
| Field |
Type |
Description |
| results |
map GetPolygonStatsResponse.ResultsEntry |
Map of layer ID to the polygon stats for that layer |
|
|
|
GetPolygonStatsResponse.ResultsEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
PolygonStats |
none |
|
|
|
GetShapePolygonStatsRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| shape |
Shape |
none |
| size |
uint32 |
If the shape is SQUARE, it is taken as the half side-length. If the shape is CIRCLE, size is taken as the radius. |
size in meters. |
| center | Point | none |
GetShapePolygonStatsResponse
| Field |
Type |
Description |
| results |
map GetShapePolygonStatsResponse.ResultsEntry |
Map of layer ID to the polygon stats for that layer |
|
|
|
GetShapePolygonStatsResponse.ResultsEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
PolygonStats |
none |
|
|
|
GetWKTPolygonStatsRequest
| Field |
Type |
Description |
| layer_ids |
repeated string |
none |
| oneof _metadata.metadata |
optional Metadata |
none |
| wkt |
string |
none |
|
|
|
GetWKTPolygonStatsResponse
| Field |
Type |
Description |
| results |
map GetWKTPolygonStatsResponse.ResultsEntry |
Map of layer ID to the polygon stats for that layer |
|
|
|
GetWKTPolygonStatsResponse.ResultsEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
PolygonStats |
none |
|
|
|
Point
A Point represents a WGS84 latitude-longitude pair.
Latitudes MUST be in the range +/-90 degrees and longitude MUST be in the
range +/-180 degrees.
| Field |
Type |
Description |
| longitude |
double |
none |
| latitude |
double |
none |
|
|
|
PointResult
Resolution and the result for each point
| Field |
Type |
Description |
| values |
repeated PointResultValue |
none |
|
|
|
PointResultValue
The result value for a point in a query.
| Field |
Type |
Description |
| query_point |
Point |
The point from the original request. |
| oneof _val.val |
optional int32 |
The actual result value. |
|
|
|
Polygon
A Polygon represents a GeoJSON polygon with just one loop (LineString).
It MUST be closed (i.e. the first and last Points are the same), with four or more Points. The inside
of a polygon loop is the left-hand side of an observer walking the edges in
vertex order (i.e. vertices MUST be counter-clockwise if viewed from above).
Reference: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.
This does not support Polygon with holes, just boundary polygon.
| Field |
Type |
Description |
| points |
repeated Point |
none |
|
|
|
PolygonResult
The raw tiff data and resolution for the result of a polygon calculation
| Field |
Type |
Description |
| oneof result.geo_tiff |
bytes |
A GeoTIFF file |
| oneof result.code |
PolygonResultCode |
A code indicating the reason why a result could not be calculated for the given polygon |
|
|
|
PolygonStats
| Field |
Type |
Description |
| oneof _mean.mean |
optional int32 |
The fields are optional to make the field presence explicit because the value can be 0. See: https://protobuf.dev/programming-guides/field_presence/ |
| oneof _min.min |
optional int32 |
none |
| oneof _max.max |
optional int32 |
none |
| oneof _std_dev.std_dev |
optional int32 |
none |
| oneof _share_above_zero.share_above_zero |
optional double |
Share (on a scale of 0 to 1) of the pixels in the provided polygon that have a value above zero. |
|
|
|
Enums
PolygonResultCode
PolygonResultCode is an error code corresponding to why polygon data was not returned.
| Name |
Number |
Description |
| POLYGON_RESULT_CODE_UNSPECIFIED |
0 |
none |
| POLYGON_RESULT_CODE_OUT_OF_BOUNDS |
1 |
Returned when the given polygon covered an area not covered by the requested dataset. |
Resolution
| Name |
Number |
Description |
| RESOLUTION_UNSPECIFIED |
0 |
none |
| RESOLUTION_1_ARC_SEC |
1 |
1 arc-sec. |
| RESOLUTION_THIRD_ARC_SEC |
2 |
1/3 arc-sec. |
| RESOLUTION_3_ARC_SEC |
3 |
3 arc-sec |
Shape
| Name |
Number |
Description |
| SHAPE_UNSPECIFIED |
0 |
none |
| SHAPE_CIRCLE |
1 |
none |
| SHAPE_SQUARE |
2 |
none |
fathom/api/v2/portfolio.proto
PortfolioService
CreatePortfolioTask
rpc CreatePortfolioTask(CreatePortfolioTaskRequest)
CreatePortfolioTaskResponse
CreatePortfolioTask creates a Portfolio Task and returns a task ID and signed URL.
The task ID is used to check on the status of the task.
The signed URL is the location to upload the Portfolio csv.
GetPortfolioTaskStatus
rpc GetPortfolioTaskStatus(GetPortfolioTaskStatusRequest)
GetPortfolioTaskStatusResponse
Fetch information about the status of a portfolio task
GetPortfolioQuotaInfo
rpc GetPortfolioQuotaInfo(.google.protobuf.Empty)
GetPortfolioQuotaInfoResponse
GetPortfolioQuotaInfo gets information about portfolios
Messages
CreatePortfolioTaskRequest
Creates a new portfolio request.
| Field |
Type |
Description |
| layer_ids |
repeated string |
Layer IDs to be requested. |
| metadata |
Metadata |
none |
|
|
|
CreatePortfolioTaskResponse
Returned on the creation of a new portfolio task
| Field |
Type |
Description |
| task_id |
string |
Task UUID. |
| upload_url |
string |
Document upload URL, it will be in form a signedURL. |
|
|
|
GetPortfolioQuotaInfoResponse
| Field |
Type |
Description |
| used |
int64 |
Total number of portfolios 'units' used this month |
| remaining |
int64 |
Number remaining for this month. Note this may be negative, in which case that's how far over the quota it's gone. |
|
|
|
GetPortfolioTaskStatusRequest
Query the status of an existing portfolio task.
| Field |
Type |
Description |
| task_id |
string |
Task UUID from CreatePortfolioTaskResponse |
|
|
|
GetPortfolioTaskStatusResponse
The status of an existing large portfolio task.
| Field |
Type |
Description |
| task_status |
TaskStatus |
Status of the task. |
| download_url |
string |
URL to download results from if the status was COMPLETE. |
| errors |
repeated string |
Any errors that occurred during processing. |
|
|
|
Enums
TaskStatus
The state of a Portfolio task.
| Name |
Number |
Description |
| TASK_STATUS_UNSPECIFIED |
0 |
none |
| TASK_STATUS_PENDING |
1 |
none |
| TASK_STATUS_COMPLETE |
2 |
none |
| TASK_STATUS_ERROR |
3 |
none |
| TASK_STATUS_IN_PROGRESS |
4 |
none |
| TASK_STATUS_EXPIRED |
5 |
none |
| TASK_STATUS_QUEUED |
6 |
none |
proto/data/data.proto
Extra data specifications for requests
Enums
Resolution
| Name |
Number |
Description |
| RESOLUTION_UNSPECIFIED |
0 |
none |
| RESOLUTION_1_ARC_SEC |
1 |
1 arc-sec. |
| RESOLUTION_THIRD_ARC_SEC |
2 |
1/3 arc-sec. TODO: change to RESOLUTION_1_3_ARC_SEC |
| RESOLUTION_3_ARC_SEC |
3 |
3 arc-sec |
proto/fathom/fathom.proto
The core specification for the Fathom API
FathomService
FathomService defines the externally facing API for querying Fathom data.
GetData
rpc GetData(GetDataRequest)
GetDataResponse
GetData returns data from a specified geometry, associated with one or more
layers.
The HTTP/JSON<->gRPC Transcoding uses a custom method just because
it'll be easier to transcode the whole request body using POST method
and avoid using query parameters with GET.
GetPolygonStats
rpc GetPolygonStats(GetPolygonStatsRequest)
GetPolygonStatsResponse
GetPolygonStats calculates some commonly used statistics for a polygonal area with the given layer IDs.
CreateAccessToken
rpc CreateAccessToken(CreateAccessTokenRequest)
CreateAccessTokenResponse
CreateAccessToken returns a JWT used to access the API.
Messages
CreateAccessTokenRequest
| Field |
Type |
Description |
| client_id |
string |
Client ID to identify the user. Required. |
| client_secret |
string |
Client Secret used with the provided Client ID. Required. |
|
|
|
CreateAccessTokenResponse
| Field |
Type |
Description |
| access_token |
string |
JWT to access the API. |
| expire_secs |
uint64 |
Seconds until this token expires |
|
|
|
Data
Data represents a subset of data from a single layer.
| Field |
Type |
Description |
| resolution |
data.Resolution |
none |
| values |
repeated Data.Value |
none |
| oneof payload.polygons |
Polygons |
none |
| oneof payload.code |
Code |
none |
|
|
|
Data.Value
| Field |
Type |
Description |
| sw_corner |
geo.Point |
none |
| query_point |
geo.Point |
none |
| oneof payload.val |
uint32 |
none |
| oneof payload.code |
Code |
none |
|
|
|
GetDataRequest
| Field |
Type |
Description |
| oneof coordinates.polygon |
geo.Polygon |
none |
| oneof coordinates.points |
geo.MultiPoint |
none |
| oneof coordinates.shp_file |
bytes |
A shp_file is the contents of a .shp shapefile only, not the entire zip archive. |
Shape file headers are at least 68 bytes |
| layers | Layers | Layer IDs for the request |
| metadata | map GetDataRequest.MetadataEntry | Extra metadata for the request |
GetDataRequest.MetadataEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
string |
none |
|
|
|
GetDataResponse
| Field |
Type |
Description |
| results |
map GetDataResponse.ResultsEntry |
Mapping from layer_id to the data result. |
|
|
|
GetDataResponse.ResultsEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
Data |
none |
|
|
|
GetPolygonStatsRequest
| Field |
Type |
Description |
| polygon |
geo.Polygon |
The polygon to fetdh data for |
| layers |
Layers |
Layer IDs for the request |
| metadata |
map GetPolygonStatsRequest.MetadataEntry |
Extra metadata for the request |
|
|
|
GetPolygonStatsRequest.MetadataEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
string |
none |
|
|
|
GetPolygonStatsResponse
| Field |
Type |
Description |
| stats |
map GetPolygonStatsResponse.StatsEntry |
Mapping from layer_id to the stats result. |
|
|
|
GetPolygonStatsResponse.StatsEntry
| Field |
Type |
Description |
| key |
string |
none |
| value |
PolygonStats |
none |
|
|
|
Layers
| Field |
Type |
Description |
| oneof ids.layer_ids |
Layers.Identifiers |
none |
|
|
|
Layers.Identifiers
| Field |
Type |
Description |
| ids |
repeated string |
none |
|
|
|
PolygonStats
| Field |
Type |
Description |
| oneof _mean.mean |
optional int32 |
The fields are optional to make the field presence explicit because the value can be 0. See: https://protobuf.dev/programming-guides/field_presence/ |
| oneof _min.min |
optional int32 |
none |
| oneof _max.max |
optional int32 |
none |
| oneof _stddev.stddev |
optional int32 |
none |
|
|
|
Polygons
| Field |
Type |
Description |
| geo_tiffs |
repeated bytes |
none |
|
|
|
Enums
Code
This is used to explain why a value has not been returned for a point or polygon.
Usually NO_DATA means that the requested layer does not have data for the requested area.
| Name |
Number |
Description |
| UNSPECIFIED |
0 |
none |
| NO_DATA |
1 |
none |
| PERMANENT_WATER |
2 |
none |
proto/geo/geo.proto
Data specifications for requests
Messages
LineString
A LineString is an array of two or more Points.
| Field |
Type |
Description |
| points |
repeated Point |
none |
|
|
|
MultiPoint
| Field |
Type |
Description |
| points |
repeated Point |
none |
|
|
|
Point
A Point represents a WGS84 latitude-longitude pair.
Latitudes MUST be in the range +/-90 degrees and longitude MUST be in the
range +/-180 degrees.
| Field |
Type |
Description |
| longitude |
double |
none |
| latitude |
double |
none |
|
|
|
Polygon
A Polygon represents a GeoJSON polygon. Each LineString MUST be closed (i.e.
the first and last Points are the same), with four or more Points. The inside
of a polygon loop is the left-hand side of an observer walking the edges in
vertex order (i.e. vertices MUST be counter-clockwise if viewed from above).
Reference: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6
| Field |
Type |
Description |
| lines |
repeated LineString |
none |
|
|
|