Quick Start

Get your first satellite image in 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 your profile settings and claim you API key.

You will get a secure key like this:

JqUhiQYb.fg6UFvPtestZkuiKrpQ5VluWhSIXwlvcyUEtestP7AWZEMqJp9AWQk2TXVsxDtestqCt

This API key have 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 the call 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 every of your organisation customer. 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": "[e-mail]" }'

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

Python

import json
import requests

GRANIOT_API_ENDPOINT = 'https://app.graniot.com/api/'
HEADERS = {
  'Content-Type': "application/json", 
  'x-api-key': 'JqUhiQYb.fg6UFvPifAbZkuiKrpQ5VluWhSIXwlvcyUE06d4P7AWZEMqJp9AWQk2TXVsxDXWxqCt'
}

path = 'accounts/'

data = { 'account_email': '[e-mail]' }

res = requests.post(f"{GRANIOT_API_ENDPOINT}{path}", headers=HEADERS, json=data)
account = res.json()

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

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

// Set your API key before making the request
GRANIOT_API_ENDPOINT = 'https://app.graniot.com/api/'
HEADERS = {
  'Content-Type': "application/json", 
  'Graniot-Account': 'acc-91d246tr0e-73rt1b-11ejhe-b0c0-02002',
  'x-api-key': 'JqUhiQYb.fg6UFvPifAbZkuiKrpQ5VluWhSIXwlvcyUE06d4P7AWZEMqJp9AWQk2TXVsxDXWxqCt'
}


path = 'farms/'

payload = {
    "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
                            ]
                        ]
                    ]
                }
            }
        }
    ]
}

res = requests.post(f"{GRANIOT_API_ENDPOINT}{path}", headers=HEADERS, json=payload)
parcel = res.json()



# 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
}

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.