BasemapsAPI

Wrapper class for interacting with the Planet Basemaps API. Provides methods for creating, managing, and downloading orders.

See the Planet Basemaps API documentation for more details: https://developers.planet.com/docs/apis/basemaps/

Example usage

from cast_planet import BasemapApi

basemaps = BasemapApi(api_key='your api key here')

basemaps.search_mosaics('monthly')

Searching for basemaps using the BaseMApAOISearch

Searching and ordering base map imagery usually requires a combination of both the BasemapApi and the OrdersApi. In this case, the BaseMapAOISearch class has been created to search and order moasics from a single class.

from cast_planet import BaseMapAOISearch

aoi_search = BaseMapAOISearch(api_key='your-api-key')

aoi = {
  "type": "Polygon",
  "properties": {
    "name": "Washington County, Arkansas"
  },
  "coordinates": [
      [
        [-94.5342, 35.9746],
        [-94.5342, 36.2414],
        [-94.0893, 36.2414],
        [-94.0893, 35.9746],
        [-94.5342, 35.9746]
      ]
    ]
}

aoi_search.order_mosaic_geojson(['global_monthly_2016_01_mosaic'], aoi=aoi)

API reference

BasemapApi

class cast_planet.BasemapApi(api_key, base_url='https://api.planet.com/basemaps/v1')

get_mosaic_by_id(mosaic_id)

Retrieves a specific mosaic by its unique ID.

This method fetches details of a mosaic from the Basemap API by providing its unique identifier (UUID).

Parameters:: mosaic_id (UUID) – The unique identifier of the mosaic to retrieve.
Returns:: A Mosaic object containing the details of the specified mosaic.
Return type:: Mosaic

list_mosaics()

Retrieves a list of all available mosaics from the Basemap API.

This method fetches all mosaics available through the Basemap API, potentially making multiple requests if pagination is involved.

Returns:: A list of mosaics available in the Basemap API.
Return type:: List[Mosaic]

search_mosaics(name_contains)

Searches for mosaics based on a partial match of their name.

This method queries the Basemap API for mosaics whose names contain the provided string and returns a list of matching mosaics.

Parameters:: name_contains (str) – A string that the mosaic names should contain. The search is case-sensitive.
Returns:: A list of mosaics whose names contain the search string.
Return type:: List[Mosaic]

BasemapAOISearch

class cast_planet.BaseMapAOISearch(api_key)

check_status(order)

Checks the status of a specific order, either by its OrderDetails object, UUID, or string ID.

This method queries the Orders API for the status of a particular order. It can accept either an OrderDetails instance, a UUID, or a string ID that represents the order. The status returned will reflect the current state of the order, such as whether it is queued, processing, or completed.

Parameters:: order (Union[OrderDetails, UUID, str]) – The order identifier, which can be an OrderDetails object, UUID, or string representation of the order ID.
Returns:: An OrderStatus object representing the current status of the order.
Return type:: OrderStatus

list_mosaics()

Retrieves a list of available mosaics from the Basemap API.

This method interacts with the Basemap API to fetch all available mosaics. It serves as a way to get a collection of mosaics that can later be used to create orders.

Returns:: A list of mosaic names or objects as returned by the Basemap API.
Return type:: List[str]

order_mosaic_geojson(mosaic_names, aoi, projection=None, email_notification=False)

Creates an order for mosaics based on a provided Area of Interest (AOI) in GeoJSON format, with optional projection settings and email notifications.

This method prepares an order for one or more mosaics based on the given AOI. The order can include optional tools such as projection and clipping. If a projection is provided, the order is reprojected accordingly. An email notification can be sent to the address associated with the API key when the order is complete.

Parameters:

mosaic_names (List[str]) – A list of mosaic names that should be included in the order. Each name corresponds to a basemap mosaic available in the Basemap API.
aoi (Union[PolygonModel, MultiPolygonModel]) – The Area of Interest (AOI) in GeoJSON format. This defines the geographic area for which the mosaics are requested.
projection (Optional[str]) – An optional string that specifies the coordinate reference system (CRS) for the order, such as “EPSG:4326” (WGS84).
email_notification (bool) – A boolean flag indicating whether an email notification should be sent to the address associated with the API key upon order completion. Default is False.

Returns:

An OrderDetails object that contains information about the created order.

Return type:

OrderDetails

Models

pydantic model cast_planet.basemap.models.Mosaic

Show JSON schema

{
   "title": "Mosaic",
   "type": "object",
   "properties": {
      "_links": {
         "$ref": "#/$defs/MosaicLinks"
      },
      "bands": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Bands"
      },
      "bbox": {
         "items": {
            "type": "number"
         },
         "maxItems": 4,
         "minItems": 4,
         "title": "Bbox",
         "type": "array"
      },
      "coordinate_system": {
         "title": "Coordinate System",
         "type": "string"
      },
      "datatype": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Datatype"
      },
      "first_acquired": {
         "format": "date-time",
         "title": "First Acquired",
         "type": "string"
      },
      "grid": {
         "anyOf": [
            {
               "$ref": "#/$defs/MosaicGrid"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "id": {
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "interval": {
         "title": "Interval",
         "type": "string"
      },
      "item_types": {
         "items": {
            "type": "string"
         },
         "title": "Item Types",
         "type": "array"
      },
      "last_acquired": {
         "format": "date-time",
         "title": "Last Acquired",
         "type": "string"
      },
      "level": {
         "title": "Level",
         "type": "integer"
      },
      "name": {
         "title": "Name",
         "type": "string"
      },
      "product_type": {
         "title": "Product Type",
         "type": "string"
      },
      "quad_download": {
         "default": false,
         "title": "Quad Download",
         "type": "boolean"
      }
   },
   "$defs": {
      "MosaicGrid": {
         "properties": {
            "quad_pattern": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Quad Pattern"
            },
            "quad_size": {
               "title": "Quad Size",
               "type": "number"
            },
            "resolution": {
               "title": "Resolution",
               "type": "number"
            }
         },
         "required": [
            "quad_size",
            "resolution"
         ],
         "title": "MosaicGrid",
         "type": "object"
      },
      "MosaicLinks": {
         "properties": {
            "_self": {
               "title": " Self",
               "type": "string"
            },
            "quads": {
               "title": "Quads",
               "type": "string"
            },
            "tiles": {
               "title": "Tiles",
               "type": "string"
            }
         },
         "required": [
            "_self",
            "quads",
            "tiles"
         ],
         "title": "MosaicLinks",
         "type": "object"
      }
   },
   "required": [
      "_links",
      "bbox",
      "coordinate_system",
      "first_acquired",
      "id",
      "interval",
      "item_types",
      "last_acquired",
      "level",
      "name",
      "product_type"
   ]
}

Fields:

bands (int | None)
bbox (List[float])
coordinate_system (str)
datatype (str | None)
first_acquired (datetime.datetime)
grid (cast_planet.basemap.models.MosaicGrid | None)
id (uuid.UUID)
interval (str)
item_types (List[str])
last_acquired (datetime.datetime)
level (int)
links (cast_planet.basemap.models.MosaicLinks)
name (str)
product_type (str)
quad_download (bool)

field bands: Optional[int] = None

field bbox: List[float] [Required]

Constraints:

min_length = 4
max_length = 4

field coordinate_system: str [Required]

field datatype: Optional[str] = None

field first_acquired: datetime [Required]

field grid: Optional[MosaicGrid] = None

field id: UUID [Required]

field interval: str [Required]

field item_types: List[str] [Required]

field last_acquired: datetime [Required]

field level: int [Required]

field links: MosaicLinks [Required] (alias '_links')

field name: str [Required]

field product_type: str [Required]

field quad_download: bool = False

pydantic model cast_planet.basemap.models.MosaicGrid

Show JSON schema

{
   "title": "MosaicGrid",
   "type": "object",
   "properties": {
      "quad_pattern": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Quad Pattern"
      },
      "quad_size": {
         "title": "Quad Size",
         "type": "number"
      },
      "resolution": {
         "title": "Resolution",
         "type": "number"
      }
   },
   "required": [
      "quad_size",
      "resolution"
   ]
}

Fields:

quad_pattern (str | None)
quad_size (float)
resolution (float)

field quad_pattern: Optional[str] = None

field quad_size: float [Required]

field resolution: float [Required]

pydantic model cast_planet.basemap.models.MosaicLinks

Show JSON schema

{
   "title": "MosaicLinks",
   "type": "object",
   "properties": {
      "_self": {
         "title": " Self",
         "type": "string"
      },
      "quads": {
         "title": "Quads",
         "type": "string"
      },
      "tiles": {
         "title": "Tiles",
         "type": "string"
      }
   },
   "required": [
      "_self",
      "quads",
      "tiles"
   ]
}

Fields:

quads (str)
tiles (str)

field quads: str [Required]

field tiles: str [Required]

pydantic model cast_planet.basemap.models.MosaicsResponse

Show JSON schema

{
   "title": "MosaicsResponse",
   "type": "object",
   "properties": {
      "_links": {
         "$ref": "#/$defs/ResponseLinks"
      },
      "mosaics": {
         "items": {
            "$ref": "#/$defs/Mosaic"
         },
         "title": "Mosaics",
         "type": "array"
      }
   },
   "$defs": {
      "Mosaic": {
         "properties": {
            "_links": {
               "$ref": "#/$defs/MosaicLinks"
            },
            "bands": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Bands"
            },
            "bbox": {
               "items": {
                  "type": "number"
               },
               "maxItems": 4,
               "minItems": 4,
               "title": "Bbox",
               "type": "array"
            },
            "coordinate_system": {
               "title": "Coordinate System",
               "type": "string"
            },
            "datatype": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Datatype"
            },
            "first_acquired": {
               "format": "date-time",
               "title": "First Acquired",
               "type": "string"
            },
            "grid": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/MosaicGrid"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null
            },
            "id": {
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "interval": {
               "title": "Interval",
               "type": "string"
            },
            "item_types": {
               "items": {
                  "type": "string"
               },
               "title": "Item Types",
               "type": "array"
            },
            "last_acquired": {
               "format": "date-time",
               "title": "Last Acquired",
               "type": "string"
            },
            "level": {
               "title": "Level",
               "type": "integer"
            },
            "name": {
               "title": "Name",
               "type": "string"
            },
            "product_type": {
               "title": "Product Type",
               "type": "string"
            },
            "quad_download": {
               "default": false,
               "title": "Quad Download",
               "type": "boolean"
            }
         },
         "required": [
            "_links",
            "bbox",
            "coordinate_system",
            "first_acquired",
            "id",
            "interval",
            "item_types",
            "last_acquired",
            "level",
            "name",
            "product_type"
         ],
         "title": "Mosaic",
         "type": "object"
      },
      "MosaicGrid": {
         "properties": {
            "quad_pattern": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Quad Pattern"
            },
            "quad_size": {
               "title": "Quad Size",
               "type": "number"
            },
            "resolution": {
               "title": "Resolution",
               "type": "number"
            }
         },
         "required": [
            "quad_size",
            "resolution"
         ],
         "title": "MosaicGrid",
         "type": "object"
      },
      "MosaicLinks": {
         "properties": {
            "_self": {
               "title": " Self",
               "type": "string"
            },
            "quads": {
               "title": "Quads",
               "type": "string"
            },
            "tiles": {
               "title": "Tiles",
               "type": "string"
            }
         },
         "required": [
            "_self",
            "quads",
            "tiles"
         ],
         "title": "MosaicLinks",
         "type": "object"
      },
      "ResponseLinks": {
         "properties": {
            "_self": {
               "title": " Self",
               "type": "string"
            },
            "_next": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": " Next"
            }
         },
         "required": [
            "_self"
         ],
         "title": "ResponseLinks",
         "type": "object"
      }
   },
   "required": [
      "_links",
      "mosaics"
   ]
}

Fields:

links (cast_planet.basemap.models.ResponseLinks)
mosaics (List[cast_planet.basemap.models.Mosaic])

field links: ResponseLinks [Required] (alias '_links')

field mosaics: List[Mosaic] [Required]

pydantic model cast_planet.basemap.models.OrderStatus

Show JSON schema

{
   "title": "OrderStatus",
   "type": "object",
   "properties": {
      "state": {
         "$ref": "#/$defs/OrderState"
      },
      "last_message": {
         "title": "Last Message",
         "type": "string"
      }
   },
   "$defs": {
      "OrderState": {
         "enum": [
            "queued",
            "running",
            "failed",
            "success",
            "partial",
            "cancelled"
         ],
         "title": "OrderState",
         "type": "string"
      }
   },
   "required": [
      "state",
      "last_message"
   ]
}

Fields:

last_message (str)
state (cast_planet.orders.models.order_details.OrderState)

field last_message: str [Required]

field state: OrderState [Required]

pydantic model cast_planet.basemap.models.ResponseLinks

Show JSON schema

{
   "title": "ResponseLinks",
   "type": "object",
   "properties": {
      "_self": {
         "title": " Self",
         "type": "string"
      },
      "_next": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": " Next"
      }
   },
   "required": [
      "_self"
   ]
}

Fields:

next (str | None)

field next: Optional[str] = None (alias '_next')