API Quickstart

The goal of this part of the documentation is to give a quickstart instructions on how to use SpaceKnow API.

• Authenticate. You received a SpaceKnow account with user name (email) and password. SpaceKnow API uses JWT Bearer Token authentication.

  • First, you need to obtain a token by calling the OAuth endpoint.

  • For subsequent API calls, use header Authorization with value Bearer <token>.

• Asynchronous APIs. Most of our APIs are asynchronous, see Asynchronous APIs for details.

  • Such API is started by calling .../initiate endpoint which returns a pipeline ID on success.

  • Status of a pipeline can be polled using Tasking API.

  • Once a pipeline has finished, its status will change to RESOLVED and its result can be then retrieved using .../retrieve endpoint.

  • Both Search for imagery and Run analysis endpoints mentioned below are asynchronous.

• Search for imagery.

  • The flow starts with searching for imagery (“scenes”). See Search Scenes for details.

  • We have several scenes which are free of charge to use, so you probably want to start with those, see Free scenes. To narrow the search down to actually find one of the free scenes, we recommend using an appropriate extent and start and end datetimes in search API call. You can identify the scenes in results by their sceneId.

• Run analysis. Once you have the scene, you can run analysis over it. See Kraken Release API.

  • Use scene ID of the free scene found above. For mapTypes use ["imagery"] to get only image tiles. For real usage, you can set any algos you have permission to access to.

• Get mercator tiles. When Kraken release finishes, you obtain mapId and tiles available for your finished map. See Grid API and Grid API reference.

  • For zoom, x and y use one of the tiles returned in the previous call. The tiles are returned as zoom, x, y triples. You can also request any of the child WebMercator tiles up to maxZoom. See Web Mercator Tiles tool to play with this system.