Embedded Maps

With embedded maps, we provide satellite images to partner applications with minimal UI development effort.

A few lines of code on the backend will allow you to create a link for the embedded map to display directly in your frontend UI.

In order to get started with the Graniot API you need to create an account in the Graniot APP.

This step is essential to obtain the bearer token that will allow you to generate the link to the embeddable maps.

How It Works

Create an account via the API using your API key
Receive the embedded_url in the response - this URL contains the authentication token
Add filter parameters (optional) to customize which parcels, farms, or data to display
Embed in your application using an iframe or open directly in the browser

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-0242ac130002",
#   "account_email": "[email protected]",
#   "embedded_url": "https://embed.graniot.com/?auth_id=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzA1NDk3NDIwLCJpYXQiOjE3MDU0ODY2MjAsImp0aSI6ImRiYzRhNmZjNDI3MTRhZGE5NWM4Y2YwMDMyMjM1ZjNjIiwiaWQiOjc0Nn0.ZKpAG0sVAbibxJEKPSS0hbYmH--lahQKJhEtPO7Jau4",
#   "account_access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzA1NDk3NDIwLCJpYXQiOjE3MDU0ODY2MjAsImp0aSI6IjIzOWQzZGM2MDRmYzRmODNhNGNmNDQyMDQ3NDI3N2ZmIiwiaWQiOjc0Nn0.PbUJGOTQaL2Z6dZZ0DcwDW8BM_rp2saRqDz7MLAlHWY"
#  }

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': '[email protected]' }

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

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

Simply use the "embedded_url" to display the embedded map with satellite images to your users or view it directly in the browser.

The embedded map also provides useful filtering capabilities. Here is a complete list of the accepted URL params:

key

Description

auth_id

JWT token to view the authenticated embedded map. This is automatically included in the embedded_url returned by the API.

resolution

Choose the resolution of the images to display. Available values include DEFORESTATION for deforestation analysis view. By default, the 10x10 meter resolution will be displayed.

parcels

Filter by parcel IDs. Multiple parameters with this key can be provided (e.g., &parcels=123&parcels=456). By default, all parcels will be displayed.

farms

Filter by farm IDs. Multiple parameters with this key can be provided (e.g., &farms=789&farms=101). By default, all farms will be displayed.

metadata[key]

Filter parcels by custom metadata. Replace key with your metadata field name (e.g., metadata[Supplier ID]=ABC-123). Spaces in keys should be encoded as + or %20.

Using Filters

You can append query parameters to the embedded_url to filter the displayed data.

Show deforestation analysis:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&resolution=DEFORESTATION

Filter by metadata (e.g., Supplier ID):

https://embed.graniot.com/?auth_id=YOUR_TOKEN&metadata[Supplier+ID]=YOUR_SUPPLIER_ID

Combine multiple filters:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&metadata[Supplier+ID]=YOUR_SUPPLIER_ID&resolution=DEFORESTATION

Filter by specific parcels:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&parcels=12345&parcels=12346

Filter by farm:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&farms=1937

When using metadata keys with spaces, encode the space as + or %20. For example, Supplier ID becomes Supplier+ID or Supplier%20ID.

Embedding in Your Application

To embed the map in your web application, use an iframe:

<iframe
  src="https://embed.graniot.com/?auth_id=YOUR_TOKEN"
  width="100%"
  height="500"
  frameborder="0"
  allow="fullscreen">
</iframe>

You can also embed with filters:

<iframe
  src="https://embed.graniot.com/?auth_id=YOUR_TOKEN&resolution=DEFORESTATION&metadata[Supplier+ID]=ABC-123"
  width="100%"
  height="500"
  frameborder="0"
  allow="fullscreen">
</iframe>

Token Expiration & Refresh

The auth_id token in the embedded_url expires after 3 hours for security reasons. When the token expires, users will see an authentication error and the map will not load.

To refresh the token, request a new embedded_url from the API:

curl https://app.graniot.com/api/accounts/acc-52a220de-73e9-11ee-8cc3-0242ac130002/ \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

# Response includes a new embedded_url with fresh token
# {
#   "id": "acc-52a220de-73e9-11ee-8cc3-0242ac130002",
#   "account_email": "[email protected]",
#   "embedded_url": "https://embed.graniot.com/?auth_id=NEW_TOKEN_HERE",
#   "account_access": "NEW_JWT_TOKEN_HERE"
# }

import requests

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

account_id = 'acc-52a220de-73e9-11ee-8cc3-0242ac130002'
res = requests.get(f"{GRANIOT_API_ENDPOINT}accounts/{account_id}/", headers=HEADERS)
account = res.json()

# Use the new embedded_url
new_embedded_url = account['embedded_url']

For long-running integrations, consider implementing a token refresh mechanism that periodically fetches a new embedded_url before the current token expires.