Protocol Documentation

Table of Contents

• fathom/api/v2/common.proto

  • Metadata

• fathom/api/v2/fathom.proto

  • CreateAccessTokenRequest
  • CreateAccessTokenResponse
  • GetGeoJSONPointsDataRequest
  • GetGeoJSONPointsDataRequest.PointsGeojsonEntry
  • GetGeoJSONPolygonDataRequest
  • GetGeoJSONPolygonDataRequest.PolygonGeojsonEntry
  • GetGeoJSONPolygonStatsRequest
  • GetGeoJSONPolygonStatsRequest.PolygonGeojsonEntry
  • GetLargeGeoJSONPolygonDataRequest
  • GetLargeGeoJSONPolygonDataRequest.PolygonGeojsonEntry
  • GetLargeGeoJSONPolygonDataResponse
  • GetLargeGeoJSONPolygonDataResponse.ResultCodesEntry
  • GetLargePolygonDataRequest
  • GetLargePolygonDataResponse
  • GetLargePolygonDataResponse.ResultCodesEntry
  • GetLargeWKTPolygonDataRequest
  • GetLargeWKTPolygonDataResponse
  • GetLargeWKTPolygonDataResponse.ResultCodesEntry
  • GetPointsDataRequest
  • GetPointsDataResponse
  • GetPointsDataResponse.ResultsEntry
  • GetPolygonDataRequest
  • GetPolygonDataResponse
  • GetPolygonDataResponse.ResultsEntry
  • GetPolygonStatsRequest
  • GetPolygonStatsResponse
  • GetPolygonStatsResponse.ResultsEntry
  • GetShapePolygonStatsRequest
  • GetShapePolygonStatsResponse
  • GetShapePolygonStatsResponse.ResultsEntry
  • GetWKTPolygonStatsRequest
  • GetWKTPolygonStatsResponse
  • GetWKTPolygonStatsResponse.ResultsEntry
  • Point
  • PointResult
  • PointResultValue
  • Polygon
  • PolygonResult
  • PolygonStats
  • QuotePointsRequest
  • QuotePointsResponse
  • QuotePolygonRequest

  • QuotePolygonResponse

  • PolygonResultCode

  • Resolution

  • Shape

  • FathomService

• fathom/api/v2/portfolio.proto

  • CreatePortfolioTaskRequest
  • CreatePortfolioTaskResponse
  • GetPortfolioQuotaInfoResponse
  • GetPortfolioTaskStatusRequest

  • GetPortfolioTaskStatusResponse

  • TaskStatus

  • PortfolioService

• Scalar Value Types

Top

fathom/api/v2/common.proto

Metadata

Metadata for requests made to the API.

Field	Type	Label	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.

Top

fathom/api/v2/fathom.proto

CreateAccessTokenRequest

CreateAccessTokenRequest is the message for requesting an API access token.

Field	Type	Label	Description
client_id	string		Client ID to identify the user. Required.
client_secret	string		Client Secret used with the provided Client ID. Required.

CreateAccessTokenResponse

CreateAccessTokenResponse contains the API access token and its expiration time.

Field	Type	Label	Description
access_token	string		JWT to access the API.
expire_secs	uint64		Seconds until this token expires

GetGeoJSONPointsDataRequest

GetGeoJSONPointsDataRequest is the message for requesting data for points defined in a GeoJSON object.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which data is requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
points_geojson	GetGeoJSONPointsDataRequest.PointsGeojsonEntry	repeated	A GeoJSON object representing the points for which data is requested. This should be a map conforming to GeoJSON structure.

GetGeoJSONPointsDataRequest.PointsGeojsonEntry

Field	Type	Label	Description
key	string
value	google.protobuf.Value

GetGeoJSONPolygonDataRequest

GetGeoJSONPolygonDataRequest is the message for requesting raster data for a polygon defined in a GeoJSON object.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which data is requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
polygon_geojson	GetGeoJSONPolygonDataRequest.PolygonGeojsonEntry	repeated	A GeoJSON object representing the polygon for which data is requested. This should be a map conforming to GeoJSON structure.

GetGeoJSONPolygonDataRequest.PolygonGeojsonEntry

Field	Type	Label	Description
key	string
value	google.protobuf.Value

GetGeoJSONPolygonStatsRequest

GetGeoJSONPolygonStatsRequest is the message for requesting statistics for a polygon defined in a GeoJSON object.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which statistics are requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
polygon_geojson	GetGeoJSONPolygonStatsRequest.PolygonGeojsonEntry	repeated	A GeoJSON object representing the polygon for which statistics are requested. This should be a map conforming to GeoJSON structure.

GetGeoJSONPolygonStatsRequest.PolygonGeojsonEntry

Field	Type	Label	Description
key	string
value	google.protobuf.Value

GetLargeGeoJSONPolygonDataRequest

GetLargeGeoJSONPolygonDataRequest is the message for requesting data for a large polygon defined in a GeoJSON object, where results are returned as a download link.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which data is requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
polygon_geojson	GetLargeGeoJSONPolygonDataRequest.PolygonGeojsonEntry	repeated	A GeoJSON object representing the polygon for which data is requested. This should be a map conforming to GeoJSON structure.

GetLargeGeoJSONPolygonDataRequest.PolygonGeojsonEntry

Field	Type	Label	Description
key	string
value	google.protobuf.Value

GetLargeGeoJSONPolygonDataResponse

GetLargeGeoJSONPolygonDataResponse contains the download URL for large GeoJSON polygon data results and result codes per layer.

Field	Type	Label	Description
download_url	string		URL to download results of the request query.
result_codes	GetLargeGeoJSONPolygonDataResponse.ResultCodesEntry	repeated	Mapping of layer ID to result code for the polygon. If the code was OUT_OF_BOUNDS, that polygon will not be in the zip file returned in download_url.

GetLargeGeoJSONPolygonDataResponse.ResultCodesEntry

Field	Type	Label	Description
key	string
value	PolygonResultCode

GetLargePolygonDataRequest

GetLargePolygonDataRequest is the message for requesting data for a large polygon, where results are returned as a download link.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which data is requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
polygon	Polygon		The polygon defining the area for which data is requested.

GetLargePolygonDataResponse

GetLargePolygonDataResponse contains the download URL for large polygon data results and result codes per layer.

Field	Type	Label	Description
download_url	string		URL to download results of the request query.
result_codes	GetLargePolygonDataResponse.ResultCodesEntry	repeated	Mapping of layer ID to result code for the polygon. If the code was OUT_OF_BOUNDS, that polygon will not be in the zip file returned in download_url.

GetLargePolygonDataResponse.ResultCodesEntry

Field	Type	Label	Description
key	string
value	PolygonResultCode

GetLargeWKTPolygonDataRequest

GetLargeWKTPolygonDataRequest is the message for requesting data for a large polygon defined in WKT format, where results are returned as a download link.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which data is requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
wkt	string		A Well-Known Text (WKT) string representing the polygon for which data is requested.

GetLargeWKTPolygonDataResponse

GetLargeWKTPolygonDataResponse contains the download URL for large WKT polygon data results and result codes per layer.

Field	Type	Label	Description
download_url	string		URL to download results of the request query.
result_codes	GetLargeWKTPolygonDataResponse.ResultCodesEntry	repeated	Mapping of layer ID to result code for the polygon. If the code was OUT_OF_BOUNDS, that polygon will not be in the zip file returned in download_url.

GetLargeWKTPolygonDataResponse.ResultCodesEntry

Field	Type	Label	Description
key	string
value	PolygonResultCode

GetPointsDataRequest

GetPointsDataRequest is the message for requesting data for a list of points and layers.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which data is requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
points	Point	repeated	List of points for which data is requested. Must contain at least one point.

GetPointsDataResponse

GetPointsDataResponse contains the data results for a points query, mapped by layer ID.

Field	Type	Label	Description
results	GetPointsDataResponse.ResultsEntry	repeated	Map of layer ID to the points result for that layer

GetPointsDataResponse.ResultsEntry

Field	Type	Label	Description
key	string
value	PointResult

GetPolygonDataRequest

GetPolygonDataRequest is the message for requesting raster data for a given polygon and layers.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which data is requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
polygon	Polygon		The polygon defining the area for which data is requested.

GetPolygonDataResponse

GetPolygonDataResponse contains the raster data results for a polygon query, mapped by layer ID.

Field	Type	Label	Description
results	GetPolygonDataResponse.ResultsEntry	repeated	Map of layer ID to the polygon result for that layer

GetPolygonDataResponse.ResultsEntry

Field	Type	Label	Description
key	string
value	PolygonResult

GetPolygonStatsRequest

GetPolygonStatsRequest is the message for requesting statistics for a given polygon and layers.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which statistics are requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
polygon	Polygon		The polygon defining the area for which statistics are requested.

GetPolygonStatsResponse

GetPolygonStatsResponse contains the statistical results for a polygon query, mapped by layer ID.

Field	Type	Label	Description
results	GetPolygonStatsResponse.ResultsEntry	repeated	Map of layer ID to the polygon stats for that layer

GetPolygonStatsResponse.ResultsEntry

Field	Type	Label	Description
key	string
value	PolygonStats

GetShapePolygonStatsRequest

GetShapePolygonStatsRequest is the message for requesting statistics for a predefined shape (e.g., circle, square).

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which statistics are requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
shape	Shape		The type of predefined geometric shape (e.g., CIRCLE, SQUARE).
size	uint32		Size of the shape in meters. 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 | | The center point of the shape. |

GetShapePolygonStatsResponse

GetShapePolygonStatsResponse contains the statistical results for a shape polygon query, mapped by layer ID.

Field	Type	Label	Description
results	GetShapePolygonStatsResponse.ResultsEntry	repeated	Map of layer ID to the polygon stats for that layer

GetShapePolygonStatsResponse.ResultsEntry

Field	Type	Label	Description
key	string
value	PolygonStats

GetWKTPolygonStatsRequest

GetWKTPolygonStatsRequest is the message for requesting statistics for a polygon defined in WKT format.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which statistics are requested. Must contain at least one ID.
metadata	Metadata	optional	Optional metadata for the request.
wkt	string		A Well-Known Text (WKT) string representing the polygon for which statistics are requested.

GetWKTPolygonStatsResponse

GetWKTPolygonStatsResponse contains the statistical results for a WKT polygon query, mapped by layer ID.

Field	Type	Label	Description
results	GetWKTPolygonStatsResponse.ResultsEntry	repeated	Map of layer ID to the polygon stats for that layer

GetWKTPolygonStatsResponse.ResultsEntry

Field	Type	Label	Description
key	string
value	PolygonStats

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	Label	Description
longitude	double		The longitude of the point, in decimal degrees. Must be between -180 and 180.
latitude	double		The latitude of the point, in decimal degrees. Must be between -90 and 90.

PointResult

PointResult contains a list of PointResultValue for a specific layer, representing data for multiple queried points.

Field	Type	Label	Description
values	PointResultValue	repeated	A list of result values, one for each point queried for this layer.

PointResultValue

PointResultValue holds the data for a single queried point, including the original point and its value.

Field	Type	Label	Description
query_point	Point		The point from the original request.
val	int32	optional	The actual result value. This is optional because a point might be out of bounds or have no data, in which case the value will not be present.

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	Label	Description
points	Point	repeated	A list of points defining the polygon's boundary. Must contain at least 4 points, with the first and last being identical.

PolygonResult

PolygonResult represents the outcome of a polygon query for a single layer, containing either GeoTIFF data or a result code.

Field	Type	Label	Description
geo_tiff	bytes		A GeoTIFF file
code	PolygonResultCode		A code indicating the reason why a result could not be calculated for the given polygon

PolygonStats

PolygonStats contains various statistical measures calculated for a given polygon and layer. The fields are optional to make the field presence explicit because the value can be 0. See: https://protobuf.dev/programming-guides/field_presence/

Field	Type	Label	Description
mean	int32	optional	The mean (average) value of the pixels within the queried polygon for this layer.
min	int32	optional	The minimum value of the pixels within the queried polygon for this layer.
max	int32	optional	The maximum value of the pixels within the queried polygon for this layer.
std_dev	int32	optional	The standard deviation of the pixel values within the queried polygon for this layer.
share_above_zero	double	optional	Share (on a scale of 0 to 1) of the pixels in the provided polygon that have a value above zero.

QuotePointsRequest

QuotePointsRequest is the message for requesting a cost quote for a points data query.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which a quote is requested. Must contain at least one ID.
points	Point	repeated	List of points for which a quote is requested. Must contain at least one point.

QuotePointsResponse

QuotePointsResponse contains the cost quote for a points data query.

Field	Type	Label	Description
total	double		The total estimated cost for the query.
currency	string		The currency of the total cost (e.g., "USD").

QuotePolygonRequest

QuotePolygonRequest is the message for requesting a cost quote for a polygon data query.

Field	Type	Label	Description
layer_ids	string	repeated	List of layer identifiers for which a quote is requested. Must contain at least one ID.
polygon	Polygon		The polygon for which a quote is requested.

QuotePolygonResponse

QuotePolygonResponse contains the cost quote for a polygon data query.

Field	Type	Label	Description
total	double		The total estimated cost for the query.
currency	string		The currency of the total cost (e.g., "USD").

PolygonResultCode

PolygonResultCode is an code corresponding to why polygon data may not have been returned.

Name	Number	Description
POLYGON_RESULT_CODE_UNSPECIFIED	0
POLYGON_RESULT_CODE_OUT_OF_BOUNDS	1	Returned when the given polygon covered an area not covered by the requested dataset.
POLYGON_RESULT_CODE_OK	2	Returned when the given polygon was computed successfully. Should only be returned by the large polygon endpoint.

Resolution

Resolution defines the spatial resolution of the data layers.

Name	Number	Description
RESOLUTION_UNSPECIFIED	0
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

Shape defines the types of predefined geometric shapes that can be used for querying statistics.

Name	Number	Description
SHAPE_UNSPECIFIED	0
SHAPE_CIRCLE	1	A circular shape.
SHAPE_SQUARE	2	A square shape.

FathomService

FathomService defines the externally facing API for querying Fathom data.

Method Name	Request Type	Response Type	Description
GetPolygonData	GetPolygonDataRequest	GetPolygonDataResponse	Returns data in tiff format for the given polygon from supplied layers.
GetPointsData	GetPointsDataRequest	GetPointsDataResponse	Returns data for given points (locations) from supplied layers.
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	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	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	GetPolygonStatsRequest	GetPolygonStatsResponse	Returns statistics data retrieved from making geo-query to given polygon and from the layers.
GetShapePolygonStats	GetShapePolygonStatsRequest	GetShapePolygonStatsResponse	Returns statistics for the supplied layers using the primitive polygon shape described in the request.
GetWKTPolygonStats	GetWKTPolygonStatsRequest	GetWKTPolygonStatsResponse	Returns statistics for the supplied layers using the wkt polygon described in the request.
CreateAccessToken	CreateAccessTokenRequest	CreateAccessTokenResponse	Returns a token used to access the API.
QuotePoints	QuotePointsRequest	QuotePointsResponse	Quote the cost to get points data
QuotePolygon	QuotePolygonRequest	QuotePolygonResponse	Quote the cost to get polygon data
GetLargePolygonData	GetLargePolygonDataRequest	GetLargePolygonDataResponse	Returns data as a link to a compressed archive of 1 tif per layer for the given polygon from supplied layers.
GetLargeWKTPolygonData	GetLargeWKTPolygonDataRequest	GetLargeWKTPolygonDataResponse	Returns data as a link to a compressed archive of 1 tif per layer for the given polygon from supplied layers using WKT.
GetLargeGeoJSONPolygonData	GetLargeGeoJSONPolygonDataRequest	GetLargeGeoJSONPolygonDataResponse	Returns data as a link to a compressed archive of 1 tif per layer for the given polygon from supplied layers using GeoJSON.

Top

fathom/api/v2/portfolio.proto

CreatePortfolioTaskRequest

Creates a new portfolio request.

Field	Type	Label	Description
layer_ids	string	repeated	Layer IDs to be requested.
metadata	Metadata		Optional metadata for the request, typically including a project ID.

CreatePortfolioTaskResponse

Returned on the creation of a new portfolio task

Field	Type	Label	Description
task_id	string		Task UUID.
upload_url	string		Document upload URL, it will be in the form of a signed URL.

GetPortfolioQuotaInfoResponse

Contains information about the current usage and remaining quota for portfolio operations.

Field	Type	Label	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	Label	Description
task_id	string		Task UUID from CreatePortfolioTaskResponse

GetPortfolioTaskStatusResponse

The status of an existing large portfolio task.

Field	Type	Label	Description
task_status	TaskStatus		Status of the task.
download_url	string		URL to download results from if the status was COMPLETE.
errors	string	repeated	Any errors that occurred during processing. This field is typically populated when task_status is TASK_STATUS_ERROR.

TaskStatus

The state of a Portfolio task.

Name	Number	Description
TASK_STATUS_UNSPECIFIED	0	Default, zero-value status. Should not be explicitly set or expected by clients.
TASK_STATUS_PENDING	1	Task has been created and is awaiting further action (e.g., file upload) or initial processing.
TASK_STATUS_COMPLETE	2	Task processing finished successfully. Results are available for download.
TASK_STATUS_ERROR	3	Task processing failed due to one or more errors.
TASK_STATUS_IN_PROGRESS	4	Task is currently being actively processed.
TASK_STATUS_EXPIRED	5	Task has expired. This can occur if the upload window for the portfolio CSV has passed, or if the results are no longer available for download.
TASK_STATUS_QUEUED	6	Task has been accepted and is waiting in a queue for processing resources to become available.

PortfolioService

Method Name	Request Type	Response Type	Description
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	GetPortfolioTaskStatusRequest	GetPortfolioTaskStatusResponse	Fetch information about the status of a portfolio task
GetPortfolioQuotaInfo	.google.protobuf.Empty	GetPortfolioQuotaInfoResponse	GetPortfolioQuotaInfo gets information about portfolios

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)