SkyFi Platform API

# Skyfi Platform API is your SataaS (Satellite as a Service). 🚀 ## Documentation sources - [Swagger documentation](https://app.skyfi.com/platform-api/docs) - [Redoc documentation](https://app.skyfi.com/platform-api/redoc) - [OpenAPI JSON Specification](https://app.skyfi.com/platform-api/openapi.json) ## Ordering - **Task** new Day/Multispectral/SAR images products with various resolutions - **Archive images** from our catalog - Get the delivirables directly in your **AWS S3**, **Google Cloud Storage** or **Azure Blob Storage** buckets - Get scientific **GeoTiff** and **PNG** for every order - Archival imagery order delivery is usually within 24 hours. - Tasking imagery order delivery is subject to the users tasking window specifications. Tasking orders will deliver within 48 hours of image capture. ## Notifications - Get notified for new archive images with custom filters - Delivered to your specific webhook that can be different for each filter on your account ## Delivery Get your imagery on the most used storage platforms - AWS S3, Google Cloud Storage or Azure Blob Storage ### Delivery to AWS S3 bucket - Set the delivery driver to `S3` - provide the required delivery parameters to connect to the `S3` bucket: `s3_bucket_id`, `aws_region`, `aws_access_key` and `aws_secret_key`, ```json "deliveryDriver": "S3", "deliveryParams": { "s3_bucket_id": "my-bucket", "aws_region": "us-east-1", "aws_access_key": "AKIABCDEF01230123...", "aws_secret_key": "58vf0U8...", "subfolder": "mymain01/mysub02" // optional } ``` ### Delivery to Google Cloud Storage bucket - Set the delivery driver to `GS` - provide the project, bucket id and credentials for connection: `gs_project_id`, `gs_bucket_id` and a service account credentials in `gs_credentials` ```json "deliveryDriver": "GS", "deliveryParams": { "gs_project_id": "my-eo-project-id", "gs_bucket_id": "eo_images_bucket_001", "gs_credentials": { "type": "service_account", "project_id": "my-eo-project-id", "private_key_id": "abcdef123123123", "private_key": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----", "client_email": "service-account-name@my-eo-project-id.iam.gserviceaccount.com", "client_id": "101010123", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://service.url/", }, "subfolder": "mymain01/mysub02" // optional } ``` ### Delivery to Azure Blob Storage We support two authentication schemas - through an account connection string or through an Azure Entra App client secret credentials: #### 1. Use Azure's account `connection_string` - Set the delivery driver to `AZURE` - provide the storage container name in `azure_container_name` and a connection string for the credentials as `azure_connection_string`: ```json "delivery_driver": "AZURE", "delivery_params": { "azure_container_name": "skyficontainer", "azure_connection_string": "...", "subfolder": "mymain01/mysub02" // optional } ``` #### 2. Use Azure's Entra App credentials - Set the delivery driver to `AZURE` - provide the storage account name in `azure_account_name` - provide the container name in `azure_container_name` - provide Azure Entra App tenant id, client id and client secret in: `azure_tenant_id`, `azure_client_id` and `azure_client_secret` - make sure to grant the Entra app the following permissions to the storage account: - `Storage Blob Data Contributor` - `Storage Queue Data Contributor` ```json "delivery_driver": "AZURE", "delivery_params": { "azure_account_name": "skyfiaccount", "azure_container_name": "skyficontainer", "azure_tenant_id": "...", "azure_client_id": "...", "azure_client_secret": "...", "subfolder": "mymain01/mysub02" // optional } ``` ### Order redelivery In case of problems with the delivery bucket, delivery parameter mistakes during ordering or if the delivery images are required in another place, one can change the delivery settings of a specific order. If the images were already delivered to the original destination, a new upload will be triggered redelivering the artefacts to the new bucket. Example: ```json POST https://app.skyfi.com/platform-api/orders/<ORDER_ID>/redelivery Accept: application/json Content-Type: application/json X-Skyfi-Api-Key: <API_KEY> { "deliveryDriver": "GS|S3|AZURE|...", // new delivery driver "deliveryParams": { ... // new delivery parameters } } ``` ### Folder structure The artefacts associated with an order will be uploaded to a folder named after the `order_id`. If you need to add a prefix to the folder structure, you can utilise the optional parameter `subfolder` in the `deliveryParams` object. ## Area of interest specifics ### Format All **AOI** fields are expected to be a simple convex **POLYGON** in the [WKT format](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry), e.g. ``` POLYGON ((-97.672442134274 30.289674402322873, -97.67245401025714 30.244570392925723, -97.72440367372722 30.244570392925723, -97.72441554971037 30.289674402322873, -97.672442134274 30.289674402322873)) ``` #### AOI limits: - orders should not have more than 500 vertices - archive searhes should not have more than 500 vertices & area more than 500,000 sqkm - notifications should not have more than 500 vertices & area more than 500,000 sqkm ### Calculate the size of the AOI in sqkm The link below is a Notebook to help you calculate the size of your Area of Interest (AOI) in sqkm. This calculation is essential for determining the order cost and ensuring compliance with our AOI constraints, such as minimum and maximum area requirements. Please note that the notebook will only generate size and not cost, but cost can be generated using our pricing guidelines [here](https://skyfi.com/files/SkyFi_Pricing_2025.pdf). To access the Notebook and learn how the AOI area is calculated, please use the following link: [Click here to access the Notebook](https://colab.research.google.com/drive/1yM2dfCFupCe1exrbhkinHDsenJ8HSp-b) Here's a brief overview of the steps involved: 1. Open the provided notebook using the provided link. 2. Create a copy of the notebook in your personal Google Drive or preferred environment. 3. Update the polygon with your specific AOI. 4. Follow the provided code and instructions to input the AOI square polygon coordinates, either manually or from previous steps of generating the AOI. 5. Run the cell associated with the AOI area calculation. The notebook will provide the area of the AOI in square kilometers. By utilizing the provided Notebook, you will be able to calculate the area of your AOI accurately. This is helpful for determining the order cost and verifying compliance with our AOI constraints, such as minimum and maximum area limitations. Please note that the provided notebook assumes a basic understanding of Python programming. In case you encounter any issues or have further questions, feel free to reach out at [api@skyfi.com](mailto:api@skyfi.com) for assistance. ### Generate an AOI with a center point To identify a polygonal Area of Interest in sq. km. given a center point, you can use the provided Python notebook. [Click here to access the Notebook](https://colab.research.google.com/drive/15Bf81qL5m5x3g_-1vGe5yxZu7pGVjFy2) Here's a brief overview of the steps involved: 1. Open the provided notebook by clicking on the link above. 2. Make a copy of the notebook to your personal Google Drive or preferred environment. 3. Change the values of the center point and the desired area in sqkm 4. Execute the notebook cells in order, ensuring that any required dependencies are installed. 5. Retrieve the generated AOI square polygon from the output. These coordinates can be used in your API requests to obtain satellite imagery for your specific area. By following these instructions, you will be able to define a customized AOI square polygon based on a center point and a desired area size. This polygon can then be used in this API to order satellite imagery for your specific area of interest. Please note that the provided notebook assumes a basic understanding of Python programming. In case you encounter any issues or have further questions, feel free to reach out at [api@skyfi.com](mailto:api@skyfi.com) for assistance. ## Opendata Sentinel1 and Sentinel2 images can be ordered through this API using the `SAR`, `DAY`, or `MULTISPECTRAL` products on the `LOW` resolution. We support other opendata products which will have the `price_for_one_square_km` set to 0. Ordering these images will be free of charge. Finding all of our opendata options can be done on our website https://app.skyfi.com/explore/open or through the `/archives` endpoint specifying the `openData: true` request option. ## Pass Prediction and Selection ### Overview When creating tasking orders, you can use pass prediction (feasibility) results to select specific satellite passes. This ensures your order uses the exact satellite pass you evaluated during feasibility checks. ### Planet Pass Selection For Planet tasking orders, you can specify a `provider_window_id` from the feasibility response: 1. **Get feasibility results** with available passes from the `/feasibility` endpoint 2. **Select a specific pass** from the opportunities list, which includes a `provider_window_id` 3. **Include the provider_window_id** in your tasking order request: ```json POST https://app.skyfi.com/platform-api/order-tasking { "aoi": "POLYGON(...)", "window_start": "2025-01-20T00:00:00Z", "window_end": "2025-01-25T23:59:59Z", "product_type": "DAY", "resolution": "VERY_HIGH", "provider_window_id": "550e8400-e29b-41d4-a716-446655440000", // From feasibility response "required_provider": "PLANET", // ... other parameters } ``` When `provider_window_id` is provided for Planet orders, the system will task that specific satellite pass, ensuring you get exactly what you evaluated during feasibility. ### Umbra SAR Pass Selection For Umbra SAR tasking orders, pass selection works differently - it's based on the **AOI combined with date and time window** rather than a window ID: 1. **Get feasibility results** with available passes from the `/feasibility` endpoint 2. **Note the specific pass timing** you want (each pass has precise start/end times) 3. **Create your tasking order** with a time window that matches the desired pass: ```json POST https://app.skyfi.com/platform-api/order-tasking { "aoi": "POLYGON(...)", // Must match the AOI used in pass-prediction "window_start": "2025-01-20T14:30:00Z", // Align with specific pass start time "window_end": "2025-01-20T14:45:00Z", // Align with specific pass end time "product_type": "SAR", "resolution": "VERY_HIGH", "required_provider": "UMBRA", "sar_product_types": ["SICD", "GEC"], // ... other SAR parameters } ``` **Important for Umbra**: The combination of AOI + time window determines which pass is selected. To ensure you get a specific pass: - Use the exact same AOI from pass-prediction - Set your window_start and window_end to tightly match the desired pass timing - The Umbra system will select the matching pass ## Webhook Events ### Order Event Webhook When you create an order with a `webhook_url` parameter, we'll send HTTP POST requests to your endpoint whenever the order status changes. Our webhook client has a timeout of 2 seconds and will retry up to 3 times until receiving a 200 response. #### Webhook Payload Structure ```json { "order_info": { // Full order information (TaskingOrderResponse or ArchiveOrderResponse) "id": "uuid", "order_type": "TASKING|ARCHIVE", "status": "current_status", // ... other order fields }, "event": { "status": "triggering_status", "timestamp": "2024-01-01T00:00:00Z", "message": "optional message" } } ``` #### Possible Webhook Event Statuses Your webhook will be called when the order transitions to any of these statuses: - **CREATED** - Order has been created - **STARTED** - Order processing has started - **PAYMENT_FAILED** - Payment processing failed - **PLATFORM_FAILED** - Internal platform error occurred - **PROVIDER_PENDING** - Order sent to satellite provider - **PROVIDER_COMPLETE** - Provider has captured/retrieved the imagery - **PROVIDER_FAILED** - Provider was unable to fulfill the order - **PROCESSING_PENDING** - Internal processing of imagery has started - **PROCESSING_COMPLETE** - Processing is complete - **PROCESSING_FAILED** - Processing failed - **DELIVERY_PENDING** - Delivery to your storage bucket has started - **DELIVERY_COMPLETED** - Imagery successfully delivered to your storage - **DELIVERY_FAILED** - Delivery to storage failed - **INTERNAL_IMAGE_PROCESSING_PENDING** - Additional image processing in progress ## Pricing To obtain information about the pricing details for our satellite imagery API, you can refer to our general pricing document. It provides a comprehensive overview of the pricing structure and associated costs. You can access the pricing document by clicking [here](https://skyfi.com/files/SkyFi_Pricing_2025.pdf). Please note that the pricing document outlines the general pricing information, but for specific details and a tailored offer, we recommend contacting us directly at [api@skyfi.com](mailto:api@skyfi.com). Our team will be happy to assist you in determining the pricing that best suits your needs. To receive a specific offer and initiate the integration process, please reach out to us at [api@skyfi.com](mailto:api@skyfi.com). Our dedicated team will promptly respond to your inquiry and provide you with the necessary information to proceed. API keys are available to all SkyFi accounts. Free accounts can place open data orders (up to 1 per day) and can also order paid imagery with a credit card attached to their profile. Pro accounts get higher daily open data limits (up to 5 per day) and advanced billing options. To manage your account, visit [app.skyfi.com](https://app.skyfi.com). For additional questions or to set up advanced billing, please email [api@skyfi.com](mailto:api@skyfi.com) and our dedicated team will respond promptly. ## Getting Started To get started with the SkyFi API, you'll need an API key. API keys are available to all SkyFi accounts and can be found in the My Profile section at [app.skyfi.com](https://app.skyfi.com). We recommend starting with open data orders, which are delivered at no cost, to ensure your delivery setup is working correctly. Free accounts can place up to 1 open data order per day, while Pro accounts can place up to 5 per day. To place open data orders, ensure the following search parameters: - resolution: low - sensor: day, multispectral, or sar __For additional support or questions about API access, please reach out to [api@skyfi.com](mailto:api@skyfi.com).__ ### Example Search Archives for Open Data Before ordering archive satellite imagery, you first need to search our archives to find specific images that match your criteria. This search step allows you to find assets in the open data catalog that covers your area of interest. Once you find suitable images in the search results, you can use their unique archive IDs to place an order for delivery. ```json POST https://app.skyfi.com/platform-api/archives Accept: application/json Content-Type: application/json X-Skyfi-Api-Key: {{API_KEY}} { "aoi": "POLYGON ((-97.72161725693583 30.285736865030987, -97.72162534407455 30.248516744000742, -97.76449625592544 30.248516744000742, -97.76450434306416 30.285736865030987, -97.72161725693583 30.285736865030987))", "openData": true, "productTypes": ["DAY", "MULTISPECTRAL", "SAR"], "resolution": "LOW", "fromDate": "2025-01-01T00:00:00+00:00", "toDate": "2025-12-31T23:59:59+00:00", } ``` ### Example archive order, SENTINEL2 open data catalog, DAY, LOW, 10m image: ```json POST https://app.skyfi.com/platform-api/order-archive Accept: application/json Content-Type: application/json X-Skyfi-Api-Key: <API_KEY> { "aoi": "POLYGON ((-97.72161725693583 30.285736865030987, -97.72162534407455 30.248516744000742, -97.76449625592544 30.248516744000742, -97.76450434306416 30.285736865030987, -97.72161725693583 30.285736865030987))", "archiveId": "db4794dd-da6a-45b4-ac6e-b9e50e36bb29", // example archiveId for ARCHIVE orders "deliveryDriver": "GS", "deliveryParams": { "gs_project_id": "<GS_PROJECT_NAME>", ... "subfolder": "mysub01" // Optional } } ```