API

Forge

class picterra.ForgeClient(**kwargs)[source]
add_raster_to_detector(raster_id: str, detector_id: str)[source]

Associate a raster to a detector

This a beta function, subject to change.

Parameters:

  • detector_id (str) – The id of the detector

  • raster_id (str) – The id of the raster

Raises:

APIError – There was an error uploading the file to cloud storage

create_detector(name: str | None = None, detection_type: str = 'count', output_type: str = 'polygon', training_steps: int = 500, backbone: str = 'resnet34', tile_size: int = 256, background_sample_ratio: float = 0.25) → str[source]

Creates a new detector

This a beta function, subject to change.

Please note that depending on your plan some setting cannot be different from the default ones

Parameters:

  • name (str | None) – Name of the detector

  • detection_type (str) – Type of the detector (one of ‘count’, ‘segmentation’)

  • output_type (str) – Output type of the detector (one of ‘polygon’, ‘bbox’)

  • training_steps (int) – Training steps the detector (integer between 500 & 40000)

  • backbone (str) – detector backbone (one of ‘resnet18’, ‘resnet34’, ‘resnet50’)

  • tile_size (int) – tile size (see HTTP API docs for the allowed values)

  • background_sample_ratio (float) – bg sample ratio (between 0 and 1)

Returns:

The id of the detector

Return type:

str

Raises:

APIError – There was an error while creating the detector

create_folder(name: str) → str[source]

Creates a new folder with the given name

Parameters:

name (str) – Name of the new folder

Returns:

The id of the folder

Return type:

str

Raises:

APIError – There was an error while creating the folder

create_marker(raster_id: str, detector_id: str | None, lng: float, lat: float, text: str) → dict[str, Any][source]

This is an experimental (beta) feature

Creates a marker

Parameters:

  • raster_id (str) – The id of the raster (belonging to detector) to create the marker on

  • detector_id (str | None) – The id of the detector to create the marker on. If this is None, the marker is created associated with the raster only

  • lng (float) –

  • lat (float) –

  • text (str) –

Raises:

APIError – There was an error while creating the marker

Return type:

dict[str, Any]

delete_detector(detector_id: str)[source]

Deletes a given detector by its identifier

Parameters:

detector_id (str) – The id of the detector to delete

Raises:

APIError – There was an error while trying to delete the detector

delete_raster(raster_id: str)[source]

Deletes a given raster by its identifier

Parameters:

raster_id (str) – The id of the raster to delete

Raises:

APIError – There was an error while trying to delete the raster

delete_vector_layer(vector_layer_id: str)[source]

Removes a vector layer

This a beta function, subject to change.

Parameters:

vector_layer_id (str) – The id of the vector layer to remove

download_raster_to_file(raster_id: str, filename: str)[source]

Downloads a raster to a local file

Parameters:

  • raster_id (str) – The id of the raster to download

  • filename (str) – The local filename where to save the raster image

Raises:

APIError – There was an error while trying to download the raster

download_result_to_feature_collection(operation_id: str, filename: str)[source]

Downloads the results from a detection operation to a local GeoJSON file.

Results are stored as a FeatureCollection of Multipolygon. Each feature has a ‘class_name’ property indicating the corresponding class name

Parameters:

  • operation_id (str) – The id of the operation to download. This should be a detect operation

  • filename (str) – The local filename where to save the results

download_result_to_file(operation_id: str, filename: str)[source]

Downloads a set of results to a local GeoJSON file

Deprecated since version 1.0.0: Use download_result_to_feature_collection instead

Parameters:

  • operation_id (str) – The id of the operation to download

  • filename (str) – The local filename where to save the results

download_vector_layer_to_file(vector_layer_id: str, filename: str)[source]

Downloads a vector layer

This a beta function, subject to change.

Parameters:

  • vector_layer_id (str) – The id of the vector layer to download

  • filename (str) – existing file to save the vector layer in, as a feature collection of polygons

edit_detector(detector_id: str, name: str | None = None, detection_type: str | None = None, output_type: str | None = None, training_steps: int | None = None, backbone: str | None = None, tile_size: int | None = None, background_sample_ratio: float | None = None)[source]

Edit a detector

This a beta function, subject to change.

Please note that depending on your plan some settings may not be editable.

Parameters:

  • detector_id (str) – identifier of the detector

  • name (str | None) – Name of the detector

  • detection_type (str | None) – The type of the detector (one of ‘count’, ‘segmentation’)

  • output_type (str | None) – The output type of the detector (one of ‘polygon’, ‘bbox’)

  • training_steps (int | None) – The training steps the detector (int in [500, 40000])

  • backbone (str | None) – detector backbone (one of ‘resnet18’, ‘resnet34’, ‘resnet50’)

  • tile_size (int | None) – tile size (see HTTP API docs for the allowed values)

  • background_sample_ratio (float | None) – bg sample ratio (between 0 and 1)

Raises:

APIError – There was an error while editing the detector

edit_raster(raster_id: str, name: str | None = None, folder_id: str | None = None, captured_at: str | None = None, identity_key: str | None = None, multispectral_band_specification: dict | None = None, cloud_coverage: int | None = None, user_tag: str | None = None)[source]

Edits an already existing raster.

Parameters:

  • name (str | None) – New human-readable name for this raster

  • folder_id (str | None) – Id of the new folder for this raster (move is in another project)

  • captured_at (str | None) – new ISO-8601 date and time at which this raster was captured, YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]; e.g. “2020-01-01T12:34:56.789Z”

  • identity_key (str | None) – New personal identifier for this raster.

  • multispectral_band_specification (dict | None) – The new band specification, see https://docs.picterra.ch/advanced-topics/multispectral

  • cloud_coverage (int | None) – Raster cloud coverage new percentage

  • user_tag (beta) – Raster tag

  • raster_id (str) –

Returns:

The id of the edited raster

Return type:

str

edit_vector_layer(vector_layer_id: str, name: str | None = None, color: str | None = None)[source]

Edits a vector layer

This a beta function, subject to change.

Parameters:

  • vector_layer_id (str) – The id of the vector layer to remove

  • name (str | None) – new name

  • color (str | None) – new color

get_authorization_grants(kind: Literal['folder', 'detector'], resource_id: str)[source]

beta function. Get the authorization grants for a given resource.

Parameters:

  • kind (Literal['folder', 'detector']) – The kind of resource to get the grants for

  • resource_id (str) – The ID of the resource

Returns:

A dictionary containing the authorization grants for the resource.

See https://app.picterra.ch/public/apidocs/v2#tag/authorization/operation/getGrants

Return type:

dict

get_raster(raster_id: str) → dict[str, Any][source]

Get raster information

Parameters:

raster_id (str) – id of the raster

Raises:

APIError – There was an error while getting the raster information

Returns:

Dictionary of the information

Return type:

dict

get_user_info() → dict[source]

Get information about the current user

This endpoint is in alpha stage and may change without warning.

Return type:

dict

import_raster_from_remote_source(raster_name: str, folder_id: str, source_id: str, aoi_filename: str, method: Literal['streaming'] = 'streaming') → str[source]

Import a raster from a remote imagery source given a GeoJSON file for the AOI

Parameters:

  • raster_name (str) – Name of the new raster

  • folder_id (str) – The id of the folder / project the raster will live in

  • source_id (str) – The id of the remote imagery source to import from

  • filename – The filename of a GeoJSON file. This should contain a FeatureCollection of Polygon/MultiPolygon representing the AOI of the new raster

  • aoi_filename (str) –

  • method (Literal['streaming']) –

Raises:

APIError – There was an error during import

Return type:

str

list_detector_rasters(detector_id: str, page_number: int | None = None)[source]

This a beta function, subject to change.

List rasters of a detector, see ResultsPage for the pagination access pattern.

Parameters:

  • detector_id (str) – The id of the detector

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

list_detectors(search_string: str | None = None, user_tag: str | None = None, is_shared: bool | None = None, page_number: int | None = None)[source]
List all the detectors the user can access, see ResultsPage

for the pagination access pattern.

Parameters:

  • search_string (str | None) – The term used to filter detectors by name

  • user_tag (str | None) – [beta] User tag to filter detectors by

  • is_shared (bool | None) – [beta] Share status to filter detectors by

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

Returns:

A ResultsPage object that contains a slice of the list of detector dictionaries

Return type:

ResultsPage

Example

{
    'id': '42',
    'name': 'cow detector',
    'configuration': {
        'detection_type': 'count',
        'output_type': 'bbox',
        'training_steps': 787
    }
},
{
    'id': '43',
    'name': 'test5',
    'configuration': {
        'detection_type': 'segmentation',
        'output_type': 'polygon',
        'training_steps': 500
    }
}
list_folder_detectors(folder_id: str, page_number: int | None = None)[source]

List of detectors assigned to a given folder, see ResultsPage for the pagination access pattern.

This a beta function, subject to change.

Parameters:

  • folder_id (str) – The id of the folder to obtain the detectors for

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

Returns:

a ResultsPage object that contains a slice of the list of detector dictionaries, plus methods to retrieve the other pages

Return type:

ResultsPage

Example

{
    "id": "id1",
    "name": "detector1",
    "is_runnable": True,
    "user_tag": "tag1",
},
{
    "id": "id2",
    "name": "detector2",
    "is_runnable": False,
    "user_tag": "tag2",
}
list_raster_markers(raster_id: str, page_number: int | None = None)[source]

This a beta function, subject to change.

List all the markers on a raster, see ResultsPage for the pagination access pattern.

Parameters:

  • raster_id (str) – The id of the raster

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

list_raster_vector_layers(raster_id: str, search: str | None = None, detector_id: str | None = None, page_number: int | None = None)[source]

This a beta function, subject to change.

List all the vector layers on a raster, see ResultsPage

for the pagination access pattern.

Parameters:

  • raster_id (str) – The id of the raster

  • search (str | None) – Optional string to search layers by name

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

  • detector_id (str | None) –

list_rasters(folder_id: str | None = None, search_string: str | None = None, user_tag: str | None = None, max_cloud_coverage: int | None = None, captured_before: str | None = None, captured_after: str | None = None, has_vector_layers: bool | None = None, page_number: int | None = None)[source]

List of rasters metadata, see ResultsPage for the pagination access pattern.

Parameters:

  • folder_id (str | None) – The id of the folder to search rasters in

  • search_string (str | None) – The search term used to filter rasters by name

  • user_tag (str | None) – [beta] The user tag to filter rasters by

  • max_cloud_coverage (int | None) – [beta] The max_cloud_coverage of the rasters (between 0 and 100)

  • captured_before (str | None) – ISO 8601 -formatted date / time of capture we want to list the rasters since

  • captured_after (str | None) – ISO 8601 -formatted date / time of capture we want to list the rasters from

  • has_vector_layers (bool | None) – [beta] Whether or not the rasters have at least one vector layer

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

Returns:

a ResultsPage object that contains a slice of the list of raster dictionaries

Return type:

ResultsPage

Example

{
    'id': '42',
    'status': 'ready',
    'name': 'raster1',
    'folder_id': 'abc'
},
{
    'id': '43',
    'status': 'ready',
    'name': 'raster2',
    'folder_id': 'def'
}
remove_raster_detection_areas(raster_id: str)[source]

This is an experimental feature

Remove the detection areas of a raster

Parameters:

raster_id (str) – The id of the raster whose detection areas will be removed

Raises:

APIError – There was an error during the operation

run_dataset_recommendation(detector_id: str)[source]

This is an experimental feature

Runs dataset recommendation on a detector. Note that you currently have to use the UI to be able to view the recommendation markers/report.

Parameters:

detector_id (str) – The id of the detector

run_detector(detector_id: str, raster_id: str, secondary_raster_id: str | None = None) → str[source]

Runs a detector on a raster: predictions are subject to a minimum charge of 10 MP.

Parameters:

  • detector_id (str) – The id of the detector

  • raster_id (str) – The id of the raster

  • secondary_raster_id (str | None) – The id of the secondary raster. This needs to be provided to run change detectors.

Returns:

The id of the operation. You typically want to pass this

to download_result_to_feature_collection

Return type:

str

set_annotations(detector_id: str, raster_id: str, annotation_type: Literal['outline', 'training_area', 'testing_area', 'validation_area'], annotations: dict[str, Any], class_id: str | None = None)[source]

Replaces the annotations of type ‘annotation_type’ with ‘annotations’, for the given raster-detector pair.

Parameters:

  • detector_id (str) – The id of the detector

  • raster_id (str) – The id of the raster

  • annotation_type (Literal['outline', 'training_area', 'testing_area', 'validation_area']) – One of (outline, training_area, testing_area, validation_area)

  • annotations (dict[str, Any]) – GeoJSON representation of the features to upload

  • class_id (str | None) – The class id to which to associate the new annotations. Only valid if annotation_type is “outline”

set_authorization_grants(kind: Literal['folder', 'detector'], resource_id: str, grants_data: dict)[source]

beta function. Set the authorization grants for a given resource.

Parameters:
Returns:

The updated authorization grants for the resource.

Return type:

dict

set_raster_detection_areas_from_file(raster_id: str, filename: str)[source]

This is an experimental feature

Set detection areas from a GeoJSON file

Parameters:

  • raster_id (str) – The id of the raster to which to assign the detection areas

  • filename (str) – The filename of a GeoJSON file. This should contain a FeatureCollection of Polygon/MultiPolygon

Raises:

APIError – There was an error uploading the file to cloud storage

train_detector(detector_id: str)[source]

Start the training of a detector

Parameters:

detector_id (str) – The id of the detector

upload_raster(filename: str, name: str, folder_id: str | None = None, captured_at: str | None = None, identity_key: str | None = None, multispectral: bool = True, cloud_coverage: int | None = None, user_tag: str | None = None) → str[source]

Upload a raster to picterra.

Parameters:

  • filename (str) – Local filename of raster to upload

  • name (str) – A human-readable name for this raster

  • folder_id (str | None) – Id of the folder this raster belongs to; if not provided, the raster will be put in the “Picterra API Project” folder

  • captured_at (str | None) – ISO-8601 date and time at which this raster was captured, YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]; e.g. “2020-01-01T12:34:56.789Z”

  • identity_key (str | None) – Personal identifier for this raster.

  • multispectral (bool) – If True, the raster is in multispectral mode and can have an associated band specification

  • cloud_coverage (int | None) – Raster cloud coverage %.

  • user_tag (beta) – Raster tag

Returns:

The id of the uploaded raster

Return type:

str

upload_vector_layer(raster_id: str, filename: str, name: str | None = None, color: str | None = None) → str[source]

Uploads a vector layer from a GeoJSON file

This a beta function, subject to change.

Parameters:

  • raster_id (str) – The id of the raster we want to attach the vector layer to

  • filename (str) – Path to the local GeoJSOn file we want to upload

  • name (str | None) – Optional name to give to the vector layer

  • color (str | None) – Optional color of the vector layer, has an HTML hex color code (eg “#aabbcc”)

Returns:

the vector layer unique identifier

Return type:

str

picterra.APIClient

alias of ForgeClient

picterra.nongeo.nongeo_result_to_pixel(result_filename)[source]

This is a helper function to convert result obtained on non-georeferenced images in pixel. Note that this will NOT work if the image was georeferenced. So only use this function if you are uploading non-georeferenced image formats like PNG or JPEG

This is currently in beta so let us know if you find any issues

Parameters:

result_filename (str) – The file path to the GeoJSON file obtained by APIClient.download_result_to_file

Returns:

A list of polygons. Each polygon is a list of rings and each ring is a list of (x, y) tuples. For example:

[
    # This is a square with a square hole
    [[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
     [(0.4, 0.4), (0.5, 0.4), (0.5, 0.5), (0.4, 0.5), (0.4, 0.4)],
    # A triangle
    [[(0, 0), (1, 0), (1, 1), (0, 0)]]
]

Tracer

class picterra.TracerClient(**kwargs)[source]
analyze_plots(plots_group_id: str, plots_analysis_name: str, plot_ids: List[str], date_from: date, date_to: date) → str[source]

Runs the analysis for a given date over the plot ids of the specified plot group, and returns the URL where we can see the analysis in the Picterra platform.

Parameters:

  • plots_group_id (str) – id of the plots group on which we want to run the new analysis

  • plots_analysis_name (str) – name to give to the new analysis

  • plot_ids (List[str]) – list of the plot ids of the plots group to select for the analysis

  • date_from (date) – start point in time at which the analysis should be evaluated; please note that the date that make sense are methodology dependent, so please check the methodology of the plots group beforehand

  • date_to (date) – end point in time at which the analysis should be evaluated.

Returns:

the analysis id.

Return type:

str

analyze_plots_precheck(plots_group_id: str, plots_analysis_name: str, plot_ids: List[str], date_from: date, date_to: date) → dict[source]

Check the analysis for a given date over the plot ids of the specified plot group has no errors

Parameters:

  • plots_group_id (str) – id of the plots group on which we want to run the new analysis

  • plots_analysis_name (str) – name to give to the new analysis

  • plot_ids (List[str]) – list of the plot ids of the plots group to select for the analysis

  • date_from (date) – start point in time at which the analysis should be evaluated; please note that the date that make sense are methodology dependent, so please check the methodology of the plots group beforehand

  • date_to (date) – end point in time at which the analysis should be evaluated.

Returns:

the precheck data

Return type:

dict

create_plots_analysis_report(plots_analysis_id: str, report_name: str, plot_ids: List[str], report_type: str, plots_group_id: str | None = None, *, metadata: dict | None = None) → str[source]

Creates a report

Parameters:

  • plots_analysis_id (str) – id of the plots analysis

  • report_name (str) – name to give to the report

  • plot_ids (List[str]) – list of the plot ids to select for the report

  • report_type (str) – type of report to generate, as per list_plots_analysis_report_types

  • metadata (dict | None) – set of key-value pairs which may be included in the report

  • plots_group_id (str | None) –

Return type:

str

Deprecated arguments:

plots_group_id: ignored, do not provide it

Returns:

the id of the new report

Return type:

str

Parameters:

  • plots_analysis_id (str) –

  • report_name (str) –

  • plot_ids (List[str]) –

  • report_type (str) –

  • plots_group_id (str | None) –

  • metadata (dict | None) –

create_plots_analysis_report_precheck(plots_analysis_id: str, report_name: str, plot_ids: List[str], report_type: str, plots_group_id: str | None = None, *, metadata: dict | None = None) → Dict[str, Any][source]

Check creation of a report with the given parameters is ok

If the function fails, the report is not valid

Parameters:

  • plots_analysis_id (str) – id of the plots analysis

  • report_name (str) – name to give to the report

  • plot_ids (List[str]) – list of the plot ids to select for the report

  • report_type (str) – type of report to generate, as per list_plots_analyses_report_types

  • metadata (dict | None) – set of key-value pairs which may be included in the report

  • plots_group_id (str | None) –

Return type:

Dict[str, Any]

Deprecated arguments:

plots_group_id: ignored, do not provide it

Returns:

the precheck data

Return type:

dict

Parameters:

  • plots_analysis_id (str) –

  • report_name (str) –

  • plot_ids (List[str]) –

  • report_type (str) –

  • plots_group_id (str | None) –

  • metadata (dict | None) –

create_plots_group(plots_group_name: str, methodology_id: str, plots_geometries_filenames: List[str], columns: Dict[str, str] | None = None) → str[source]

Creates a new plots group.

Parameters:

  • plots_group_name (str) – user-friendly name for the group

  • methodology_id (str) – id of the methodology to use, retrieved via list_methodologies

  • plots_geometries_filenames (List[str]) – Paths to files containing the geometries of the plots the group will have

  • columns (Dict[str, str] | None) – columns to add to the group. if any

Returns:

the id of the new group.

Return type:

str

download_plots_group_to_file(plots_group_id: str, format: Literal['excel', 'geojson'], filename: str) → None[source]

Downloads a plots group to a local file

Parameters:

  • plots_group_id (str) – The id of the plots group to download

  • filename (str) – The local filename where to save the plots group

  • format (Literal['excel', 'geojson']) –

Raises:

APIError – There was an error while trying to download the plots group id

Return type:

None

get_authorization_grants(kind: Literal['plots_group', 'plots_analysis', 'methodology'], resource_id: str)[source]

beta function. Get the authorization grants for a given resource.

Parameters:

  • kind (Literal['plots_group', 'plots_analysis', 'methodology']) – The kind of resource to get the grants for

  • resource_id (str) – The ID of the resource

Returns:

A dictionary containing the authorization grants for the resource.

See https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/authorization/operation/getGrants

Return type:

dict

get_plots_analysis(plots_analysis_id: str, plots_group_id: str | None = None) → Dict[str, Any][source]

Get plots analysis information

Parameters:

  • plots_analysis_id (str) – id of the plots analysis

  • plots_group_id (str | None) –

Return type:

Dict[str, Any]

Deprecated arguments:

plots_group_id: ignored, do not provide it

Returns:

see https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/analysis/operation/getAnalysis

Return type:

dict

Parameters:

  • plots_analysis_id (str) –

  • plots_group_id (str | None) –

get_plots_analysis_report(plots_analysis_report_id: str, plots_group_id: str | None = None, plots_analysis_id: str | None = None) → Dict[str, Any][source]

Get plots analysis report information

Parameters:

  • plots_analysis_report_id (str) – id of the plots analysis report

  • plots_group_id (str | None) –

  • plots_analysis_id (str | None) –

Return type:

Dict[str, Any]

Deprecated arguments:

plots_group_id: ignored, do not provide it plots_analysis_id: ignored, do not provide it

Raises:

APIError – There was an error while getting the plots analysis report information

Returns:

see https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/reports/operation/getReportForAnalysis

Return type:

dict

Parameters:

  • plots_analysis_report_id (str) –

  • plots_group_id (str | None) –

  • plots_analysis_id (str | None) –

get_plots_group(plots_group_id: str) → dict[source]

Get plots group information

Parameters:

plots_group_id (str) – id of the plots group

Raises:

APIError – There was an error while getting the plots group information

Returns:

see https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/plots-groups/operation/getPlotsGroup

Return type:

dict

get_user_info() → dict[source]

Get information about the current user

This endpoint is in alpha stage and may change without warning.

Return type:

dict

list_methodologies(search: str | None = None, page_number: int | None = None) → ResultsPage[source]
List all the methodologies the user can access, see ResultsPage

for the pagination access pattern.

Parameters:

  • search (str | None) – The term used to filter methodologies by name

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

Returns:

See https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/plots-groups/operation/getMethodologiesList

Return type:

dict

Example

{
    'id': '42',
    'name': 'Coffee - EUDR',
},
{
    'id': '43',
    'name': 'Cattle - EUDR'
}
list_plots_analyses(plots_group_id: str, search: str | None = None, page_number: int | None = None, include_archived: bool = False) → ResultsPage[source]
List all the plots analyses the user can access, see ResultsPage

for the pagination access pattern.

This function is still beta and subject to change.

Parameters:

  • plots_group_id (str) – id of the plots group on which we want to list the analyses

  • search (str | None) – The term used to filter by name

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

  • include_archived (bool) – Defaults to false. If true, includes archived analyses in the results

Returns:

See https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/analysis/operation/getPlotsAnalysesList

Return type:

dict

list_plots_analysis_report_types(plots_analysis_id: str, plots_group_id: str | None = None, search: str | None = None) → List[Dict[str, Any]][source]

List all the plots analyses report types the user can use (see create_plots_analysis_report)

Parameters:

  • plots_analysis_id (str) – id of the plots analysis

  • search (str | None) – optional term to search report types by name, if any

  • plots_group_id (str | None) –

Return type:

List[Dict[str, Any]]

Deprecated arguments:

plots_group_id: ignored, do not provide it

Returns:

See https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/reports/operation/getReportTypesForAnalysis

Return type:

dict

Parameters:

  • plots_analysis_id (str) –

  • plots_group_id (str | None) –

  • search (str | None) –

list_plots_analysis_reports(plots_analysis_id: str, plots_group_id: str | None = None, page_number: int | None = None, include_archived: bool = False, search: str | None = None, report_type: str | None = None) → ResultsPage[source]
List all the reports belonging to a given plots analysis, see ResultsPage

for the pagination access pattern.

Parameters:

  • plots_analysis_id (str) – id of the plots analysis for which we want to list the reports

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

  • include_archived (bool) – Defaults to false. If true, includes archived analysis reports in the results

  • search (str | None) – Optional term to search report types by name

  • report_type (str | None) – Optional type of report to restrict the list by, use list_plots_analysis_report_types to know which the available report types are

  • plots_group_id (str | None) –

Return type:

ResultsPage

Deprecated arguments:

plots_group_id: ignored, do not provide it

Returns:

See https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/reports/operation/getReportsList

Return type:

dict

Parameters:

  • plots_analysis_id (str) –

  • plots_group_id (str | None) –

  • page_number (int | None) –

  • include_archived (bool) –

  • search (str | None) –

  • report_type (str | None) –

list_plots_groups(search: str | None = None, page_number: int | None = None, include_archived: bool = False, methodology: str | None = None) → ResultsPage[source]
List all the plots group the user can access, see ResultsPage

for the pagination access pattern.

This function is still beta and subject to change.

Parameters:

  • search (str | None) – The term used to filter by name

  • page_number (int | None) – Optional page (from 1) of the list we want to retrieve

  • include_archived (bool) – If true, includes archived plot groups in the results

  • methodology (str | None) – If not None, filters the groups by the methodology (eg “Coffee - EUDR”)

Returns:

See https://app.picterra.ch/public/apidocs/plots_analysis/v1/#tag/plots-groups/operation/getPlotsGroupsList

Return type:

dict

set_authorization_grants(kind: Literal['plots_group', 'plots_analysis', 'methodology'], resource_id: str, grants_data: dict)[source]

beta function. Set the authorization grants for a given resource.

Parameters:
Returns:

The updated authorization grants for the resource.

Return type:

dict

update_plots_group_plots(plots_group_id: str, plots_geometries_filenames: List[str], delete_existing_plots: bool = False)[source]

Updates the geometries of a given plots group

Parameters:

  • plots_group_id (str) – identifier for the plots group to replace

  • plots_geometries_filenames (List[str]) – List of paths to files containing the geometries of the plots the group will have

  • delete_existing_plots (bool) – If true, will remove all existing plots in the plots group before uploading new ones. If False (default), plot data uploaded is merged with existing plots.

Returns:

The creation operation result, which includes the plot group id

Return type:

dict

Utility classes

class picterra.ResultsPage(url: str, fetch: Callable[[str], Response])[source]

Interface for a paginated response from the API

Typically the endpoint returning list of objects return them splitted in pages (page 1, page 2, etc..) of a fixed dimension (eg 20). Thus each list_XX function returns a ResultsPage (by default the first one); once you have a ResultsPage for a given list of objects, you can:

  • check its length with len();

    • example: len(page)

  • access a single element with the index operator [];

    • example: page[5]

  • turn it into a list of dictionaries with list();

    • example: list(page)

  • get the next page with .next(); this could return None if the list is finished;

    • example: page.next()

You can also get a specific page passing the page number to the list_XX function

Parameters:

  • url (str) –

  • fetch (Callable[[str], requests.Response]) –

class picterra.APIError[source]

Generic API error exception