Giraffe APIs can be explored visually using the in built API explorer at (or in dev). The below examples all make the same calls, but in Python.

Authentication

The same API can be accessed as an individual user (ie. your permissions and access will match what you see in the app) or with a workspace API token (which has access to all data belonging to a given workspace regardless of sharing settings).

All API calls will require

import requests
import os

# dev <https://dev-dot-giraffe-feaso.appspot.com>
# or prod <https://app.giraffe.build>
URL = os.getenv("GIRAFFE_URL") or "<https://dev.giraffe.build>"

headers = {}
# workspace API token - get from Main menu -> Admin -> API Tokens
if os.getenv("GIRAFFE_API_TOKEN"):
    headers["Giraffe-Api-Token"] = os.getenv("GIRAFFE_API_TOKEN")
# or alternatively your personal token avialable at {URL}/api/viewCookie
elif os.getenv("GIRAFFE_SESSION"):
    headers["cookie"] = f'giraffe_session={os.getenv("GIRAFFE_SESSION")}'

print("headers", headers)
print("URL", URL)

Basic Usage

def create_model(model, data):
    return requests.post(f"{URL}/api/{model}/", json=data, headers=headers).json()

def get_models(model, params={}):
    return requests.get(f"{URL}/api/{model}/", headers=headers, params=params).json()

def get_model(model, id):
    return requests.get(f"{URL}/api/{model}/{id}/", headers=headers).json()

def update_model(model, data):
    id = data["id"]
    return requests.put(f"{URL}/api/{model}/{id}/", json=data, headers=headers).json()

def delete_model(model, id):
    requests.delete(f"{URL}/api/{model}/{id}/", headers=headers)

Projects

To get the workspace projects along with example params

# example 
params = {
	# include all projects
	'audit_mode': True,
	# include sharing meta data (ie which users, teams and workspaces a project is shared with)
	'full_permissions': True,
	# recently updated, note formate is %Y-%m-%d
	'updated_at_gte': '2022-04-01'
}
get_models('projects', params=params)

Teams

A Giraffe project can be shared with a user, team or a whole workspace. Here is an example of how to create a team, and then add a member to that team (known as a userteam).

Create a team

create_model('teams', {
    'name':name,
    'org': workspace_id,
})

Team members (userteams)

create_model('userteams', {
    'user_email': email,
    'team': team_id,
    'access_level': 'view',
})

a_users_teams = get_models('userteams', params={ 'userEmail': email })

Sharing a project with a team (teamprojects)

create_model('teamprojects', {
    'project': project_id,
    'team': team_id,
    'access_level': 'edit',
})

teams_a_project_is_shared_with = get_models('teamprojects', params={ 'projectId': projectId })

Creating multiple projects from a GeoJSON

Don’t have a geojson? Try https://mapshaper.org/ or http://geojson.io/ to convert.