Quick Start

Get your first satellite image in a few steps.

Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

To begin using the Graniot API, you need to create an account on the Graniot APP. Once you have signed up, go to Settings > Developers in the top-right menu and generate your API key.

You will get a secure key like this:

JqUhiQYb.fg6UFvPtestZkuiKrpQ5VluWhSIXwlvcyUEtestP7AWZEMqJp9AWQk2TXVsxDtestqCt

This API key has to be used on the server side and must be secret and stored securely in your web or mobile app’s server-side code (such as in an environment variable or credential management system). Don’t expose this key on a website or embed it in a mobile application.

All calls have to be performed over HTTPS to the base URL:

https://app.graniot.com/api

Authentication to the API is performed with X-API-KEY header, use -H "X-API-KEY: JqUhiQYb.fg6UFvPifAbZkuiKrpQ5VluWhSIXwlvcyUE06d4P7AWZEMqJp9AWQk2TXVsxDXWxqCt.

Connected Accounts

Every API key is associated with your organisation. You can create multiple accounts for your organisation, ideally one for each of your organisation's customers. In this way all the data can be associated to a specific account.

In order to add an account for your organisation you only need to provide an email, this email will only be used as identifier.

curl

curl https://app.graniot.com/api/accounts/ 
-X 'POST'
-H 'accept: application/json'
-H 'x-api-key: JqUhiQYb.fg6UFvPifAbZkuiKrpQ5VluWhSIXwlvcyUE06d4P7AWZEMqJp9AWQk2TXVsxDXWxqCt' 
-d '{ "account_email": "[email protected]" }'

# Response
# {
#   "id": "acc-52a220de-73e9-11ee-8cc3-024pac120002",
#   "account_email": "[email protected]",
#   "embedded_url": "https://embed.graniot.com/?auth_id=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzA1NDk3NDIwLCJpYXQiOjE3MDU0ODY2MjAsImp0aSI6ImRiYzRhNmZjNDI3MTRhZGE5NWM4Y2YwMDMyMjM1ZjNjIiwiaWQiOjc0Nn0.ZKpAG0sVAbibxJEKPSS0hbYmH--lahQKJhEtPO7Jau4",
#   "account_access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzA1NDk3NDIwLCJpYXQiOjE3MDU0ODY2MjAsImp0aSI6IjIzOWQzZGM2MDRmYzRmODNhNGNmNDQyMDQ3NDI3N2ZmIiwiaWQiOjc0Nn0.PbUJGOTQaL2Z6dZZ0DcwDW8BM_rp2saRqDz7MLAlHWY"
#  }

Python

Authenticating as a Connected Account

When you create a connected account, the response includes an account_access token. There are two ways to authenticate and perform actions on behalf of a connected account:

Option 1: API Key + Account Header (Recommended for Backend)

Use your API key with the Graniot-Account header. This method is non-expiring and should only be used server-side.

x-api-key: YOUR_API_KEY
Graniot-Account: acc-52a220de-73e9-11ee-8cc3-0242ac130002

Option 2: Bearer Token (For Frontend/Embedded)

Use the account_access JWT token. This method expires after 3 hours and is suitable for client-side applications and embedded maps.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

The account_access JWT token expires after 3 hours. To refresh it, call GET /api/accounts/{account_id}/ which returns a new account_access token and embedded_url.

For a detailed comparison and code examples, see the Authentication for Connected Accounts guide.

Add your first Farm and Parcel

Take a look at how you might call this method:

curl

curl 'https://app.graniot.com/api/farms/' 
    -X POST 
    -H 'content-type: application/json' 
    -H 'Graniot-Account': 'acc-91d246tr0e-73rt1b-11ejhe-b0c0-02002'
    -H 'x-api-key: JqUhiQYb.fg6UFvPifAbZkuiKrpQ5VluWhSIXwlvcyUE06d4P7AWZEMqJp9AWQk2TXVsxDXWxqCt' 
    --data-raw '{"farm":{"name":"Foo farm"},"parcels":[{"id":2230,"name":"Test Parcel","family":"","variety":"","geom":{"type":"Feature","properties":{"hectares":0.07328972851093106},"geometry":{"type":"Polygon","coordinates":[[[-1.101049,38.139019],[-1.100733,38.139019],[-1.100741,38.138791],[-1.10108,38.138788],[-1.101049,38.139019]]]}}}]}'


# Response
{
    "id": 1937,
    "farm_parcels": {
        "type": "FeatureCollection",
        "features": [
            {
                "id": 17446,
                "type": "Feature",
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                -1.101049,
                                38.139019
                            ],
                            [
                                -1.100733,
                                38.139019
                            ],
                            [
                                -1.100741,
                                38.138791
                            ],
                            [
                                -1.10108,
                                38.138788
                            ],
                            [
                                -1.101049,
                                38.139019
                            ]
                        ]
                    ]
                },
                "bbox": [
                    -1.10108,
                    38.138788,
                    -1.100733,
                    38.139019
                ],
                "properties": {
                    "hectares": "0.073",
                    "image_url": "SERVICE=wms&WARNINGS=False&MAXCC=100.0&Geometry=POLYGON+%28%2838.139019+-1.101049%2C+38.139019+-1.100733%2C+38.138791+-1.100741%2C+38.138788+-1.10108%2C+38.139019+-1.101049%29%29&BBOX=38.138788%2C-1.10108%2C38.139019%2C-1.100733&FORMAT=image%2Fpng&CRS=EPSG%3A4326&WIDTH=512&HEIGHT=450&REQUEST=GetMap&VERSION=1.3.0",
                    "wms_url": "https://app.graniot.com/api/wms/?access_key=vA/1B4VHLiREBszL4R/pssErCno7TwqLC8xYTkDvBaCBnq4qh4M0tsXE0%2BfFlHwpZxeotIju%2AE52miXcP2D4UExZJg/1w/w%3D%3D%2APrlpIk69spYvy5Iv0EWDPw%3D%3D%2Ag6dB%2BqJ4zhCNSiA0KyqTsg%3D%3D&layers=",
                    "deforestation": null,
                    "parcelresolution_set": [
                        {
                            "resolution": 1,
                            "last_image_date": null
                        }
                    ],
                    "key": "02bec263-78f4-4cf2-9b8d-5a388a4622d1",
                    "name": "Test Parcel",
                    "is_active": true,
                    "metadata": null
                }
            }
        ]
    },
    "name": "Foo farm",
    "type": "PRO",
    "is_active": true,
    "farm_group": null
}

Python

Just pick the wms_url parameter in the properties of the parcel and add at the end the name of the satellite layer you want to see, for example NDVI, PCD, OSAVI.

https://app.graniot.com/api/wms/?access_key=azktepnXVR/XQgxElbHzwVFeftG4VYW8WK2KSduFGj8aFiSFWT3wQl70xx48K/EjYRt6fkpExA%3D%3D%2ANcYZD1/uB6yQjgHhGBcBJw%3D%3D%2AI/hPr3g4/anarRUWMnEcew%3D%3D%2AwDDCFJxZB1w8fC5sY1MfkQ%3D%3D&layers=NDVI

NDVI image of the parcel

Explore the Satellite Data page in API Reference to see the other layers and data you can get.