Introduction
Cadasta API documentation
Users
Managing a User AccountManage Platform Users
Organization
OrganizationsOrganization Members
Project
ProjectsProject Members
Questionnaires
Questionnaires
Records
Spatial Units (a.k.a Locations)PartiesRelationships
Resources
Project ResourcesSpatial Resources

Cadasta API documentation

Welcome to Cadasta's API documentation! These docs will walk you through the different endpoints of the Cadasta platform:

This documentation is structured primarily by related functionality and topic, and then by endpoint.

Each endpoint is described using several parts:

  • The HTTP method. The primary methods you'll see here are GET, POST, PATCH, and DELETE.

  • The path, such as /api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/. All URLs referenced here require their own base path, which may be https://demo.cadasta.org, https://platform.cadasta.org or the URL of your own local instance of the platform. We recommend using https://demo.cadasta.org/ for testing.

  • Any URL parameters, a.k.a. parts of the endpoints are wrapped in brackets. In the above path, those would be {organization_slug} and {project_slug}

In addition, each combination of method and endpoint is described by a request payload, properties, and an example response.

All URLs referenced here require their own base path, which may be your own local instance of the Cadasta Platform. If you'd like to use an existing base path to explore the API, you can use the one for our demo site: https://demo.cadasta.org/.

Using the API

This API works best in one of two scenarios:

  1. You are a developer working with an individual or organization using the Cadasta Platform. If you have administrator access to the organization you're working for, you'll be able to perform many of the key functions for that organization using your authorization token.

  2. You have created a locally hosted version of the platform.

If you have any questions about using the API, do not hesitate to contact us. You can also ask questions on our gitter channel, https://gitter.im/Cadasta/cadasta.

The API is built using the Django REST framework, so you have the ability to view the API properties if you head to the API endpoint, such as https://platform.cadasta.org/api/v1/organizations/.

Requests

All requests are encoded in application/json, unless they involve some kind of file upload. Any exceptions are indicated in the documentation.

Common Response Codes

After submitting any API request, you'll get one of the following responses.

Response Description
200 , 201 The operation has been completed successfully
400 There was a problem with the request payload. Usually this means required attributes are missing or the values provided are not accepted. Only applies to the POST , PATCH and PUT requests.
401 This request requires a user to be authenticated. You either have not provided an authentication token or the authentication token provided is not valid.
403 Permission denied, the user has no permission to access this resource or perform this action.
404 Not found. (The object with the given slug or ID was not in the database.)

Formatting URLs for Accessing Specific Objects

To get, create, or modify projects, organizations, organization members and more, you'll need to access certain IDs (such as username) or a couple different kinds of slugs.

Two slugs that appear frequently are:

  • organization_slug, and
  • project_slug

You can find the organization_slug by locating the organization in the list of all organizations and then copying the value of the slug property.

You can find most project_slugs by viewing all of the projects in the Cadasta system, which returns publicly viewable projects as well as projects you have access to. If it's a private project, you must have access to it and find it by listing all of the projects in an organization.

Once you get your slugs, add them to your endpoint outside of the curly braces.

For example, to get at a specific project, you need to use the following endpoint:

If the organization_slug is sample-organization and the project_slug is sample-project, then the endpoint should look like this:

GET /api/v1/organizations/sample-organization/projects/sample-project/

This API uses many other IDs and slugs, each of which are explained along with the endpoint they are used in.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/

Pagination

When listing multiple resources, responses are paginated. This allows the server to return large datasets over a number of requests, avoiding timeouts and enabling clients to reduce wait time by making multiple requests in parallel.

Paginated responses contain the following properties:

Response Description
count Total number of resources to be returned.
next URL to next page of data ( null if not applicable)
previous URL to previous page of data ( null if not applicable)
results Array of resources that fit within the given page of data. Note: GeoJSON responses return a single object with a "type": "FeatureCollection" and data in the "features" property.

Pagination can be controlled with the following query parameters:

Query Paramter Description
limit The maximum number of items to return. By default, endpoints return 100 entries per page. Any exceptions are indicated in the documentation.
offset The starting position of the query in relation to the complete set of unpaginated items.

JSON Response

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

GeoJSON Response

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": {
    "type": "FeatureCollection",
    "features": []
  }
}

Managing a User Account

Developers who use the Cadasta Platform are required to set up a user account. You can create and register a new user through the GUI or using the API.

To register a user through the API requires you to enter the Virtual Machine and run the server. You can do so by following the steps outlined in the Cadasta README. Once inside, you can follow the API instructions on how to Register a New User / Create a New User Account.

You can use the Cadasta API to manage these accounts, provided that you have their username and password. This section outlines how to do that, focusing on endpoints that start with api/v1/account/. Here all the examples use the localhost:8000 domain, but you may need to change the domain and port according to your needs.

Account object

An account JSON object contains the following properties:

Property Type Description
username String The user's username (30 characters or fewer. Letters, digits and @/./+/-/_ only.)
full_name String The user's full name.
email String The user's email address.
email_verified Boolean Indicates whether the user has verified their email address.
last_login String Date and time of last user login.
language String The current available language codes are [ ‘en’, ‘fr’, ‘es’, ‘id’, ‘pt’, ‘it’ ] . Default is “en-us”.

Example Account JSON Object

{
  "username": "janedoe",
  "full_name": "Jane Doe",
  "email": "jane@cadasta.org",
  "email_verified": true,
  "last_login": "2016-10-25T20:20:14.192918Z",
  "language": "en",
  "measurement": "metric",
  "avatar": "https://s3-us-west-2.amazonaws.com/cadasta-platformdemo-bucket/avatars/quybdrsgicebb9t7zat3gbym.png"
}

Register a New User / Create a New User Account

Use this method and endpoint to register a new user to the platform. Note: this does not log the user in-- it simply creates a new account for them. This method is required so that users can log in and grab the authentification token later.

Request Payload

Property Type Required? Description
username String x The user's username (30 characters or fewer. Letters, digits and @/./+/-/_ only.)
full_name String The user's full name.
email String x The user's email address.
password String x The user's password.
language String The current available language codes are [ ‘en’, ‘fr’, ‘es’, ‘id’, ‘pt’‘ ] . Default is “en-us”.

Curl command example

Response

The response contains an account JSON object.

POST
/api/v1/account/register/
curl -X POST localhost:8000/api/v1/account/register/ -H 'Content-Type: application/json' --data '{"username":"yourusername", "password":"yourpassword", "email":"youremail@example.com"}'

Example Response

{
  "username": "j_smith",
  "full_name": "Joe Smith",
  "email": "joe.smith@example.com",
  "email_verified": false
}

Log a User In / Get Authorization Key

Getting your authorization token is one of the first things you need to do before using the Cadasta Platform API. That's because many endpoints of Cadasta's API require an authenticated user. To authenticate a user, you need to sign API requests with an authorization token, which you can obtain by logging the user in.

Note that logging a user into the API does not log them into the platform.

Request Payload

Property Type Required? Description
password String x The user's password.
username String x The user's username.

Curl command example

Response

The response contains a JSON object with the following properties:

Property Type Description
auth_token String The authorization token. Use it to sign requests to the API.
POST
/api/v1/account/login/
curl -X POST localhost:8000/api/v1/account/login/ --data '{"username":"yourusername", "password":"yourpassword"}'

Example Response

{
  "auth_token": "UER33kHWhdLPq9nKkvENFtLvu3FF68GQ"
}

Log a User Out

Curl command example

Logging a user out removes their authorization token. Requests cannot be signed with any token obtained previously.

Note that logging a user out of the API does not log them out of the platform.

Response

When the logout was successful, you receive an empty response with status code 200.

curl -X POST -d "username={username}&password={password}" http://demo.cadasta.org/api/v1/account/logout/
POST
/api/v1/account/logout/

Get the User Account

This method and endpoint returns the account information for the user authenticated with the request.

Curl command example

Note: The last part -H ‘Accept: application/json; indent=4’ is optional but it displays the response object nicely with indentation (as shown on the right).

Response

The response contains an account JSON object.

GET
/api/v1/account/
curl -X GET localhost:8000/api/v1/account/ -H ‘Authorization: token xxxxxxxxxxxxxxxxxxxxxx’ -H 'Accept: application/json; indent=4'

Example Response

{
  "username": "j_smith",
  "full_name": "Joe Smith",
  "email": "joe.smith@example.com",
  "email_verified": false,
  "last_login": "2016-10-20T19:20:27.848272Z"
}

Update a User Account

Update a user's credentials using this method and endpoint.

Request Payload

Property Type Required? Description
username String x The user's username (30 characters or fewer. Letters, digits and @/./+/-/_ only.)
full_name String The user's full name.
email String x The user's email address.
language String The current available language codes are [ ‘en’, ‘fr’, ‘es’, ‘id’, ‘pt’‘ ] . Default is “en-us”.

Curl command example

Note: This changes the the username from “username” to “newUserName” and the “language” from the default value “en-us” to “fr”

Response

The response contains an account JSON object.

PATCH
/api/v1/account/
curl -X PATCH localhost:8000/api/v1/account/ -H 'Authorization: token xxxxxxxxxxxxxxxxxxxxxx' -H 'Content-Type: application/json' --data '{"username":"newUserName", "email": "youremail@example.com", "language": "fr"}'

Example Response

{
  "username": "j_smith",
  "full_name": "Joe Smith",
  "email": "joe.smith@example.com",
  "email_verified": false,
  "last_login": "2016-10-20T19:20:27.848272Z"
}

Change the password

This method and endpoint changes the password for a user's account.

Request Payload

Property Type Required? Description
new_password String x The new password.
re_new_password String x A confirmation of the new password.
current_password String x The current password.

Curl command example

Response

If the password was changed successfully, an empty response with response code 204 is returned.

POST
/api/v1/account/password/
curl -X POST localhost:8000/api/v1/account/password/ -H ‘Authorization: token xxxxxxxxxxxxxxxxxxxxxx’ -H ‘Content-Type: application/json’ --data '{"new_password":"Example2017", "re_new_password": "Example2017","current_password":"OldOne2016"}'

Manage Platform Users

This section refers to endpoints that begin with /api/v1/users/.

These endpoints are for use by superusers only – individuals who have special account access for an instance of of the Cadasta Platform. They can be used as an entry point to see all users in the platform.

Platform user response object

Here is a table of the first tier properties of the users object:

Property Type Description
username String The user's username (30 characters or fewer. Letters, digits and @/./+/-/_ only.)
full_name String The user's full name.
email String The user's email associated with their account. Must be valid email address.
organizations Array An array of organizations the user is a member of. (See the organizations object table below for more information).
last_login String Date and time of last user login.
is_active Boolean Whether or not the user is active.

The organizations object contains the following properties:

Property Type Description
id String The ID of the organization.
name String The name of the organization.

Example User JSON Object

{
  "username": "janesmith",
  "full_name": "Jane Smith",
  "email": "j.smith@example.com",
  "last_login": "2016-10-20T19:20:27.848272Z",
  "is_active": true,
  "organizations": [{
    "id": "90ush89adh89shd89sah89sah",
    "name": "Cadasta"
  }, {
    "id": "kxzncjkxhziuhsaiojdioasjd",
    "name": "Foo Corp."
  }]
}

List Platform Users

This method and endpoint return all of the users in the platform.

Response

The response contains a list of user JSON objects, including the organizations the user is a member of.

GET
/api/v1/users/

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "username": "janesmith",
      "full_name": "Jane Smith",
      "email": "j.smith@example.com",
      "last_login": "2016-10-20T19:20:27.848272Z",
      "is_active": true,
      "organizations": [{
        "id": "90ush89adh89shd89sah89sah",
        "name": "Cadasta"
      }, {
        "id": "kxzncjkxhziuhsaiojdioasjd",
        "name": "Foo Corp."
      }]
    }
  ]
}

Get a Platform User

Use this method to view a single user in the platform.

Response

The response contains a user JSON object, including the organizations the user is a member of.

GET
/api/v1/users/{username}/

Example Response

{
  "username": "janesmith",
  "full_name": "Jane Smith",
  "email": "j.smith@example.com",
  "last_login": "2016-10-20T19:20:27.848272Z",
  "is_active": true,
  "organizations": [{
    "id": "90ush89adh89shd89sah89sah",
    "name": "Cadasta"
  }, {
    "id": "kxzncjkxhziuhsaiojdioasjd",
    "name": "Foo Corp."
  }]
}

Update a Platform User

Use this method and endpoint to update some of the fields associated with a specific username.

Request Payload

All fields are optional, if a field is not present in the request payload, that field will not be updated.

Property Type Required? Description
username String The user's username (30 characters or fewer. Letters, digits and @/./+/-/_ only.)
full_name String The user's full name.
email String The user's email associated with their account.
is_active Boolean Whether or not the user is active.

Response

The response contains a user JSON object that includes the organizations the user is a member of.

PATCH
/api/v1/users/{username}/

Example Response

{
  "username": "janesmith",
  "full_name": "Jane Smith",
  "email": "j.smith@example.com",
  "last_login": "2016-10-20T19:20:27.848272Z",
  "is_active": true,
  "organizations": [{
    "id": "90ush89adh89shd89sah89sah",
    "name": "Cadasta"
  }, {
    "id": "kxzncjkxhziuhsaiojdioasjd",
    "name": "Foo Corp."
  }]
}

Organizations

Organizations in Cadasta represent organizations in real life. The Cadasta API allows you to work with data associated with organizations that have been added to the platform, and to add organizations as well. The endpoints for these objects start with api/v1/organizations.

To learn more about organizations, see our documentation on Organizations.

Organization JSON object

An organization JSON object contains the following properties:

Property Type Description
id String The ID of the organization
slug String The short label of the organization; usually used in URLs.
name String The name of the organization.
description String A long-form description of the organization.
archived Boolean Indicates whether the organization has been archived.
urls Array A list of URLs to websites of this organization.
contacts Array A list of contacts for this organization. A contact is a JSON object containing name , email ( optional ) and tel ( optional ) .
Example Organization JSON Object
{
  "id": "wS3Mp76Spqu9A0Crg9bMxB2o",
  "slug": "david-org",
  "name": "David Org",
  "description": "David Org (testing)",
  "archived": false,
  "urls": [],
  "contacts": [
    {
      "tel": null,
      "name": "David",
      "email": "david@example.com"
    },
    {
      "tel": null,
      "name": "Frank",
      "email": "frank@example.com"
    }
  ]
}

List Organizations

This method returns all of the publicly available organizations in the platform.

Response

The response body is an array containing an organization JSON object.

GET
/api/v1/organizations/

Example response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "C9nWLc9znHQ5V0aaX1tmZQoN",
      "slug": "cadasta",
      "name": "Cadasta",
      "description": "",
      "archived": true,
      "urls": [],
      "contacts": []
    },
    {
      "id": "wS3Mp76Spqu9A0Crg9bMxB2o",
      "slug": "david-org",
      "name": "David Org",
      "description": "David Org (testing)",
      "archived": false,
      "urls": [],
      "contacts": [
        {
          "tel": null,
          "name": "David",
          "email": "david@example.com"
        },
        {
          "tel": null,
          "name": "Frank",
          "email": "frank@example.com"
        }
      ]
    }
  ]
}

List Organizations using a permissions filter

Using the permissions query parameter, the list of organizations can be filtered according to the permissions the authenticated user has on the individual organization.

If you want to list only organizations where the user can create projects, you request:

GET /api/v1/organizations/?permissions=project.create

To filter against more than one permission, provide a comma-separated list of these permissions.

GET /api/v1/organizations/?permissions=project.create,org.update

Organizations can be filtered using the following permissions:

Permission Description
org.view View the organization.
org.view_archived View the organization, if it's archived.
org.update Update the organization.
org.archive Archive the organization.
org.unarchive Unarchive the organization.
org.users.list List members of an organization.
org.users.add Add a member to an organization.
org.users.edit Edit the permissions of members in the organization.
org.users.remove Remove a member from the organization.
project.create Create a new project in the organization.
project.list List projects in the organization.

Response

The response body is an array containing an organization JSON object.

GET
/api/v1/organizations/?permissions={permission[,permission]}

Example response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "C9nWLc9znHQ5V0aaX1tmZQoN",
      "slug": "cadasta",
      "name": "Cadasta",
      "description": "",
      "archived": true,
      "urls": [],
      "contacts": []
    },
    {
      "id": "wS3Mp76Spqu9A0Crg9bMxB2o",
      "slug": "david-org",
      "name": "David Org",
      "description": "David Org (testing)",
      "archived": false,
      "urls": [],
      "contacts": [
        {
          "tel": null,
          "name": "David",
          "email": "david@example.com"
        },
        {
          "tel": null,
          "name": "Frank",
          "email": "frank@example.com"
        }
      ]
    }
  ]
}

Create an Organization

Use this endpoint to create a new organization. The user who creates this organization automatically becomes its first user, and thereby the administrator.

Request payload

The request payload is a JSON object containing the following properties.

Property Type Required? Description
name String x The name of the organization.
description String A long-form description of the organization.
archived Boolean Indicates whether the organization has been archived.
urls Array A list of URLs to websites of this organization.
contacts Array A list of contacts for this organization. A contact is a JSON object containing name , email ( optional ) and tel ( optional ) ; either email or tel must be provided.

Here's how you need to format your URLs:

"urls": [
  "http://www.example.org",
  "http://bethsorganization.org"
]

Here's how you need to format your contacts:

"contacts": [
  {
    "name": "Orion",
    "email": "orion@example.org",
    "tel": ""
  },
  {
    "name": "Archimedes",
    "email": "archimedes@example.org",
    "tel": "555-555-5555"
  }
]

Response

The response body contains an organization JSON object.

The response also contains the field users, which provides a list of members of this organization. In this case, there will only be one user shown: the user who created the organization.

POST
/api/v1/organizations/

Example response

{
  "id": "wS3Mp76Spqu9A0Crg9bMxB2o",
  "slug": "david-org",
  "name": "David Org",
  "description": "David Org (testing)",
  "archived": false,
  "urls": [],
  "contacts": [
    {
      "tel": null,
      "name": "David",
      "email": "david@example.org"
    },
    {
      "tel": null,
      "name": "Frank",
      "email": "Frank@example.org"
    }
  ],
  "users": [
    {
       "username": "david-palomino",
       "full_name": "David Palomino",
       "email": "dave@example.org",
       "email_verified": true,
       "last_login": "2016-10-21T23:18:45.135341Z"
    }
  ]
}

Get a Specific Organization

This method gets at a specific organization.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .

Response

The response body contains an organization JSON object.

The response also contains the field users, which provides a list of members of this organization.

GET
/api/v1/organizations/{organization_slug}/

Example Response

{
  "id": "wS3Mp76Spqu9A0Crg9bMxB2o",
  "slug": "david-org",
  "name": "David Org",
  "description": "David Org (testing)",
  "archived": false,
  "urls": [],
  "contacts": [
    {
      "tel": null,
      "name": "David",
      "email": "david@example.org"
    },
    {
      "tel": null,
      "name": "Frank",
      "email": "frank@example.org"
    }
  ],
  "users": [
    {
      "username": "Kate",
      "full_name": "Kate",
      "email": "Kate@example.org",
      "email_verified": false,
      "last_login": "2016-07-15T00:01:29.446812Z"
    }
  ]
}

Update an Organization

This method allows you to update an organization.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .

Request payload

The request payload is a JSON object containing the following properties. All properties are optional — if a property is not presented the request payload, the property will not be updated.

Property Type Required? Description
name String The name of the organization.
description String A long-form description of the organization.
archived Boolean Indicates whether the organization has been archived.
urls Array A list of URLs to websites of this organization.
contacts Array A list of contacts for this organization. A contact is a JSON object containing name , email ( optional ) and tel ( optional ) ; either email or tel must be provided.

Response

The response body contains an organization JSON object.

The response also contains the field users, which provides a list of members of this organization.

PATCH
/api/v1/organizations/{organization_slug}/

Example Response

{
  "id": "wS3Mp76Spqu9A0Crg9bMxB2o",
  "slug": "david-org",
  "name": "David Org",
  "description": "David Org (testing)",
  "archived": false,
  "urls": [],
  "contacts": [
    {
      "tel": null,
      "name": "David",
      "email": "david@example.org"
    },
    {
      "tel": null,
      "name": "Frank",
      "email": "frank@example.org"
    }
  ],
  "users": [
    {
      "username": "Kate",
      "full_name": "Kate",
      "email": "kate@example.org",
      "email_verified": false,
      "last_login": "2016-07-15T00:01:29.446812Z"
    }
    {
      "username": "Beth",
      "full_name": "Beth",
      "email": "beth@example.org",
      "email_verified": false,
      "last_login": "2016-04-17T00:01:29.446812Z"
    }
  ]
}

Organization Members

Users associated with an organization are known as members. The endpoint you need to access the members of an organization is: /api/v1/organizations/{organization_slug}/users/.

Organization Member JSON object

A member JSON object has the following properties. These properties are similar to the account JSON object, but they include whether the user is an admin of the organization in question.

Property Type Description
username String The user's username.
full_name String The user's full name.
email String The user's email associated with their Cadasta account.
email_verified Boolean Whether or not the email has been verified.
last_login String The last date of the user's login.
admin Boolean Indicates whether or not the user is an admin of the organization of which they are a member.

Example Member JSON Object

{
    "username": "Joyce",
    "full_name": "Joyce Jones",
    "email": "joyce@example.org",
    "email_verified": true,
    "last_login": "2016-10-21T23:18:45.135341Z",
    "admin": true
}

List Organization Members

Use this method to return all of the members of an organization.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .

Response

The response body is an array containing an organization JSON object.

GET
/api/v1/organizations/{organization_slug}/users/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
       "username": "Kate",
       "full_name": "Kate",
       "email": "kate@example.org",
       "email_verified": false,
       "last_login": "2016-07-15T00:01:29.446812Z"
    }
    {
       "username": "Beth",
       "full_name": "Beth",
       "email": "beth@example.org",
       "email_verified": true,
       "last_login": "2016-04-17T00:01:29.446812Z"
    }
  ]
}

Add an Organization Member

This method adds a member to the organization. Note that the person needs to have an account for this to work.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .

Request Payload

Property Type Required? Description
username String x The user's username (30 characters or fewer. Letters, digits and @/./+/-/_ only.)
admin Boolean Indicates whether the user will have admin. Defaults to false .

Response

The response is an organization member JSON object.

POST
/api/v1/organizations/{organization_slug}/users/

Example Response

{
    "username": "jane",
    "full_name": "Jane Doe",
    "email": "jane@example.org",
    "email_verified": false,
    "last_login": "2016-10-27T20:37:19.453868Z",
    "admin": false
}

Get an Organization Member

This method gets the information of a specific member of an organization. This can be helpful if you need to see whether that person is an administrator of the organization or not.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
username The username for a specific user, which can be found by listing organization members .

Response

The response includes the properties of an organization member JSON object.

GET
/api/v1/organizations/{organization_slug}/users/{username}/

Example Response

{
    "username": "jane",
    "full_name": "Jane Doe",
    "email": "jane@example.org",
    "email_verified": false,
    "last_login": "2016-10-27T20:37:19.453868Z",
    "admin": false
}

Update an Organization Member's Admin Status

This method updates the admin status of a specific member of an organization. If you need to change the user's account information, see how to update a user account.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
username The username for a specific user, which can be found by listing organization members .

Request Payload

You must provide the username and the admin status.

Property Type Required? Description
admin Boolean x Indicates whether or not the user is an admin of the organization of which they are a member.

Response

The response is an organization member JSON object.

PATCH
/api/v1/organizations/{organization_slug}/users/{username}/

Example Response

{
    "username": "jane",
    "full_name": "Jane Doe",
    "email": "jane@example.org",
    "email_verified": false,
    "last_login": "2016-10-27T20:37:19.453868Z",
    "admin": true
}

Remove an Organization Member

This method updates the information of a specific member of an organization.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
username The username for a specific user, which can be found by listing organization members .

Response

If the user was successfully deleted, an empty response with status code 204 will be returned.

DELETE
/api/v1/organizations/{organization_slug}/users/{username}/

Projects

The Cadasta API allows you work with data for projects that have been added to the platform.

Project JSON Object

A project JSON object contains the following properties.

Property Type Description
id String The ID of the project
organization Object JSON object of the project's organization .
country String The country where the project is located; represented as a two-letter ISO 3166-1 alpha-2 code.
name String The name of the project.
description String A long-form description of the project.
archived Boolean Indicates whether the project has be archived.
urls Array A list of URLs to websites of this project.
contacts Array A list of contacts for this project. A contact is a JSON object containing name , email (optional) and tel (optional).
users Array JSON Object of all the project's members // ADD LINK
access String Indicates whether access to the project is restricted; is either "public" or "private" .
slug String The short label of the project; usually used in URLs.
extent Object A GeoJSON geometry of the project's geographic area.
Example Project JSON Object
{
  "id": "z82wdtrf8m9sh56bdph6qeig",
  "organization": {
    "id": "3r48bi5xy8xzfu5d94smpb7a",
    "slug": "example-organization",
    "name": "Example Organization",
    "description": "Example Organization is a non-profit, non-governmental organization working to empower poor and marginalized individuals and communities.",
    "archived": false,
    "extent": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -0.17329216003417966,
            51.51194758264939
          ],
          [
            -0.17303466796874997,
            51.511092905004745
          ],
          [
            -0.1709747314453125,
            51.51023821132554
          ],
          [
            -0.17329216003417966,
            51.51194758264939
          ]
        ]
      ]
    },
    "urls": [
      "http://www.example.org/"
    ],
    "contacts": [
      {
        "tel": null,
        "name": "Andrew Brown",
        "email": "andrew@example.org"
      },
      {
        "tel": null,
        "name": "Megan Jones",
        "email": "megan@example.org"
      }
    ],
    "country": "NG",
    "name": "Lagos Tenure Assessment (old)",
    "description": "Security of Tenure Profiling in Lagos",
    "archived": false,
    "urls": [],
    "contacts": [],
    "access": "public",
    "slug": "lagos-tenure-assessment"
  }
}

List All Projects

Use this method to list all the publicly viewable projects in the Cadasta system. You can also see any private projects that you have access to.

Response

The response body is an array containing multiple project JSON objects.

GET
/api/v1/projects/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "pw6esdz94iztk4k23hskj73q",
      "organization": {
        "id": "rm4ahxqizjxqbzt3h8itmb3f",
        "slug": "brian-org",
        "name": "Brian Org",
        "description": "",
        "archived": false,
        "urls": [],
        "contacts": []
      },
      "country": "BD",
      "name": "Download Test",
      "description": "",
      "archived": false,
      "urls": [
        ""
      ],
      "contacts": [],
      "access": "public",
      "slug": "download-test",
      "extent": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -0.17329216003417966,
              51.51194758264939
            ],
            [
              -0.17303466796874997,
              51.511092905004745
            ],
            [
              -0.1709747314453125,
              51.51023821132554
            ],
            [
              -0.17329216003417966,
              51.51194758264939
            ]
          ]
        ]
      },
    },
    {
      "id": "jugibdxzaz5i2v3uni5bt6d9",
      "organization": {
        "id": "rm4ahxqizjxqbzt3h8itmb3f",
        "slug": "brian-org",
        "name": "Brian Org",
        "description": "",
        "archived": false,
        "urls": [],
        "contacts": []
      },
      "country": "BD",
      "name": "Import Test",
      "description": "",
      "archived": false,
      "urls": [
        ""
      ],
      "contacts": [],
      "access": "public",
      "slug": "import-test-1",
      "extent": null
    }
  ]
}

List All Projects in an Organization

To see all of the projects in an organization, use this method.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .

Response

The response body is an array containing multiple project JSON objects.

GET
/api/v1/organizations/{organization_slug}/projects/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "h8ridjt2jazkac4e97srzmh2",
      "organization": {
        "id": "gae6pjf9xygxddgyg5dq45iq",
        "slug": "example-organization",
        "name": "Example Organization",
        "description": "",
        "archived": false,
        "urls": [
          "http://example.com"
        ],
        "contacts": null
      },
      "country": "",
      "name": "Atlanta Project",
      "description": "",
      "archived": false,
      "urls": [
        "http://www.atlanta-example.org"
      ],
      "contacts": null,
      "access": "public",
      "slug": "atlanta-project",
      "extent": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -0.17329216003417966,
              51.51194758264939
            ],
            [
              -0.17303466796874997,
              51.511092905004745
            ],
            [
              -0.1709747314453125,
              51.51023821132554
            ],
            [
              -0.17329216003417966,
              51.51194758264939
            ]
          ]
        ]
      },
    },
    {
      "id": "hxk4k8aee5rh5htahhh5uenn",
      "organization": {
        "id": "gae6pjf9xygxddgyg5dq45iq",
        "slug": "example-organization",
        "name": "Example Organization",
        "description": "",
        "archived": false,
        "urls": [
          "http://example.com"
        ],
        "contacts": null
      },
      "country": "US",
      "name": "Portland Project",
      "description": "",
      "archived": false,
      "urls": [
        ""
      ],
      "contacts": [
        {
          "name": "Kate",
          "email": "kate@example.org",
          "tel": null
        },
        {
          "name": "Oliver",
          "email": "oliver@example.org",
          "tel": "444-555-6789"
        },
        {
          "name": "David",
          "email": null,
          "tel": "555-555-5555"
        }
      ],
      "access": "public",
      "slug": "portland-project",
      "extent": null
    }
  ]
}

List projects using a permissions filter

Using the permissions query parameter, the list of projects can be filtered according to the permissions the authenticated user has on the individual project.

If you want to list only project where the user can create parties, you request:

GET /api/v1/projects/?permissions=party.create

To filter against more than one permission, provide a comma-separated list of these permissions.

GET /api/v1/projects/?permissions=party.create,project.update

Projects can be filtered using the following permissions:

Permission Description
project.view View the project.
project.view_private View the project, if it is private.
project.view_archived View the project, if it is archived.
project.update Update the project.
project.archive Archive the project.
project.unarchive Unarchive the project.
project.users.list List members of an project.
project.users.add Add a member to an project.
project.users.edit Edit the permissions of members in the project.
project.users.remove Remove a member from the project.
party.list List parties in this project.
party.create Create a new party for this project.
tenure_rel.list List tenure relationships in this project.
tenure_rel.create Create a new tenure relationship for this project.
spatial.list List spatial units in this project.
spatial.create Create a new spatial unit for this project.

Filtering all projects

GET
/api/v1/projects/?permissions={permission[,permission]}

Filtering organization projects

GET
/api/v1/organizations/{organization_slug}/projects/?permissions={permission[,permission]}

Create a New Project

Use this endpoint to create a new project. Note that all projects must be connected to an organization!

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .

Request Payload

Property Type Required? Description
name String x The name of the project.
description String A long-form description of the project.
archived Boolean Indicates whether the project has be archived. Defaults to false .
urls Array A list of URLs to websites of this project.
contacts Array A list of contacts for this project. A contact is a JSON object containing name , email (optional) and tel (optional).
access String Indicates whether the project is a "public" or a "private" one. Defaults to "public" .
extent Object A GeoJSON geometry of the project's geographic area.

Response

The response body is an array containing a project JSON object.

POST
/api/v1/organizations/{organization_slug}/projects/

Example Response

{
  "id": "h8ridjt2jazkac4e97srzmh2",
  "organization": {
    "id": "gae6pjf9xygxddgyg5dq45iq",
    "slug": "example-organization",
    "name": "Example Organization",
    "description": "",
    "archived": false,
    "urls": [
      "http://example.com"
    ],
    "contacts": null
  },
  "country": "",
  "name": "Atlanta Project",
  "description": "",
  "archived": false,
  "urls": [
    "http://www.atlanta-example.org"
  ],
  "contacts": null,
  "access": "public",
  "slug": "atlanta-project",
  "extent": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -0.17329216003417966,
          51.51194758264939
        ],
        [
          -0.17303466796874997,
          51.511092905004745
        ],
        [
          -0.1709747314453125,
          51.51023821132554
        ],
        [
          -0.17329216003417966,
          51.51194758264939
        ]
      ]
    ]
  }
}

Get a Project

Use this method to get at a specific project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Response

The response body is an array containing a project JSON object.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/

Example Response

{
  "id": "hxk4k8aee5rh5htahhh5uenn",
  "organization": {
    "id": "gae6pjf9xygxddgyg5dq45iq",
    "slug": "example-organization",
    "name": "Example Organization",
    "description": "",
    "archived": false,
    "urls": [
      "http://example.com"
    ],
    "contacts": null
  },
  "country": "US",
  "name": "Portland Project",
  "description": "",
  "archived": false,
  "urls": [
    ""
  ],
  "contacts": [
    {
      "name": "Kate",
      "email": "kate@example.org",
      "tel": null
    },
    {
      "name": "Oliver",
      "email": "oliver@example.org",
      "tel": "444-555-6789"
    },
    {
      "name": "David",
      "email": null,
      "tel": "555-555-5555"
    }
  ],
  "users": [],
  "access": "public",
  "slug": "global-project",
  "extent": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -0.17329216003417966,
          51.51194758264939
        ],
        [
          -0.17303466796874997,
          51.511092905004745
        ],
        [
          -0.1709747314453125,
          51.51023821132554
        ],
        [
          -0.17329216003417966,
          51.51194758264939
        ]
      ]
    ]
  }
}

Update Basic Project Information

Use this method to update a project in an organization. The fields of the project that you can edit are shown in the request payload below.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Request Payload

Using the API, you can update any of the following fields. All of them are optional; fields left blank will remain the same following the update.

Property Type Required? Description
country String The country where the project is located; represented as a two-letter ISO 3166-1 alpha-2 code.
name String The name of the project.
description String (optional) A long-form description of the project.
archived Boolean Indicates whether the project has be archived.
urls Array A list of URLs to websites of this project.
contacts Array A list of contacts for this project. A contact is a JSON object containing name , email (optional) and tel (optional).
access String Indicates whether access to the project is restricted; is either "public" or "private" .

Response

The response body is an array containing a project JSON object.

PATCH
/api/v1/organizations/{organization_slug}/projects/{project_slug}/

Example Response

{
  "id": "hxk4k8aee5rh5htahhh5uenn",
  "organization": {
    "id": "gae6pjf9xygxddgyg5dq45iq",
    "slug": "example-organization",
    "name": "Example Organization",
    "description": "",
    "archived": false,
    "urls": [
      "http://example.com"
    ],
    "contacts": null
  },
  "country": "US",
  "name": "Portland Project",
  "description": "",
  "archived": false,
  "urls": [
    ""
  ],
  "contacts": [
    {
      "name": "Kate",
      "email": "kate@example.org",
      "tel": null
    },
    {
      "name": "Oliver",
      "email": "oliver@example.org",
      "tel": "444-555-6789"
    },
    {
      "name": "David",
      "email": null,
      "tel": "555-555-5555"
    }
  ],
  "users": [
    {
      "username": "dpalomino",
      "full_name": "David Palomino",
      "email": "dpalomino@example.org",
      "email_verified": true,
      "last_login": "2016-10-24T14:46:56.317086Z"
    },
    {
      "username": "kate",
      "full_name": "Kate",
      "email": "kate@example.org",
      "email_verified": false,
      "last_login": "2016-10-21T11:00:46.182648Z"
    }
  ],
  "access": "public",
  "slug": "portland-project",
  "extent": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -0.17329216003417966,
          51.51194758264939
        ],
        [
          -0.17303466796874997,
          51.511092905004745
        ],
        [
          -0.1709747314453125,
          51.51023821132554
        ],
        [
          -0.17329216003417966,
          51.51194758264939
        ]
      ]
    ]
  }
}

Project Members

Project members are users associated with projects in the Cadasta Platform. Using the Cadasta API, you can add, view, update, and delete project members.

The endpoint for project member objects start with /api/v1/organizations/{organization_slug}/projects/{project_slug}/users/.

Project Member JSON Object

A project member JSON object contains the following properties:

Property Type Description
username String The user's username (30 characters or fewer. Letters, digits and @/./+/-/_ only.)
full_name String The user's full name. (optional)
email String The user's email address.
email_verified Boolean Boolean indicating whether the user has verified their email address.
last_login String Date and time of last user login.
role String Indicates the role of the user on the project.

The role key resolves to:

ID Title
A Organization administrator or platform superuser (has the same permissions as a project manager)
PM Project Manager
DC Data Collector
PU Project User
Example Project Member JSON Object
{
  "username": "kate",
  "full_name": "Kate",
  "email": "kate@example.org",
  "email_verified": false,
  "last_login": "2016-10-21T11:00:46.182648Z",
  "role": "PM"
}

List Project Members

Use this method see the members of a project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Response

The response contains an array of multiple project member JSON objects.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/users/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "username": "dpalomino",
      "full_name": "David Palomino",
      "email": "dpalomino@example.org",
      "email_verified": true,
      "last_login": "2016-10-24T14:46:56.317086Z",
      "role": "DC"
    },
    {
      "username": "kate",
      "full_name": "Kate",
      "email": "kate@example.org",
      "email_verified": false,
      "last_login": "2016-10-21T11:00:46.182648Z",
      "role": "PM"
    }
  ]
}

Add a Project Member

Use this method to add a new project member to a project.

Note that project members need to already have a user account and be a member of the organization administering the project.

Learn more about creating user accounts and adding organization members.

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Request Payload

Property Type Required? Description
role String x Indicates the role of the user on the project. (PM = Project Manager, DC = Data Collector, PU = Project User)

Response

The response contains a project member JSON object.

POST
/api/v1/organizations/{organization_slug}/projects/{project_slug}/users/

Example Response

{
  "username": "jane",
  "full_name": "Jane Doe",
  "email": "jane@example.org",
  "email_verified": false,
  "last_login": "2016-10-27T20:37:19.453868Z",
  "role": "DC"
}

Get a Project Member

Use this method to see a member of a project. This can be helpful if you need to see or change their role in the project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
username The username for a specific user, which can be found by listing organization members .

Response

The response contains a project member JSON object.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/users/{username}/

Example Response

{
  "username": "jane",
  "full_name": "Jane Doe",
  "email": "jane@example.org",
  "email_verified": false,
  "last_login": "2016-10-27T20:37:19.453868Z",
  "role": "DC"
}

Update Project Member Permissions

This method allows you to update the permissions granted to a project member.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
username The username for a specific user, which can be found by listing organization members .

Request Payload

Property Type Required? Description
role String x Indicates the role of the user on the project. (PM = Project manager, DC = Data Collector, PU = Project User)

You can select one of the following permissions:

ID Title
PU Project User
DC Data Collector
PM Project Manager

Response

The response contains a project member JSON object.

PATCH
/api/v1/organizations/{organization_slug}/projects/{project_slug}/users/{username}/

Example Response

{
  "username": "jane",
  "full_name": "Jane Doe",
  "email": "jane@example.org",
  "email_verified": false,
  "last_login": "2016-10-27T20:37:19.453868Z",
  "role": "DC"
}

Remove a Project Member

This method removes a member from a project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
username The username for a specific user, which can be found by listing organization members .

Response

If the user was removed successfully from the project, an empty response with status code 204 will be returned.

DELETE
/api/v1/organizations/{organization_slug}/projects/{project_slug}/users/{username}/

Questionnaires

Each project on the Cadasta Platform requires a questionnaire, or set of questions and values, to display. The set of questions creates the essential framework for data collection.

Using the API, you can submit/replace questions in JSON format or get the questionnaire schema in JSON format. With the "Advanced" setting in the QGIS plugin, you can use the JSON structure to customally create a questionnaire while uploading data.

Note: You cannot replace a questionnaire in an active project once data has been collected.

Tip: Cadasta uses three entities to store questions: locations, parties, and relationships. Each question must be located in one of these three entities. And each questionnaire must include the five required fields (but these are not located in the location, party or relationship attributes): location_type (select_one type with custom values-- names, or keys, can only have 10 characters), tenure_type (select_one type with custom values-- names, or keys, can only have 10 characters), party_name (text field) and party_type (select_one with values that must be IN, GR, CO).

To learn more about how questionnaires work, see our documentation on Questionnaires and Custom Data Collection.

The endpoint you will use to work with questionnaires begins with:

/api/v1/organizations/{organization_slug}/projects/{project_slug}/questionnaire/

A questionnaire JSON object contains the following properties:

Property Type Description
id String The questionnaire ID.
filename String The file name of the questionnaire.
title String The questionnaire title.
id_string String The unique ID for the spreadsheet, as defined in the spreadsheet itself in the Settings tab.
xls_form String Link to an Excel spreadsheet version of the form hosted on Amazon AWS.
version String Time stamp when the questionnaire was last updated
questions Array List of questions, charted in the Questions section below.
question_groups Array List of question groups, charted in the Question Groups section below.

Question Groups

Property Type Description
id String The ID of the question group.
name String Question group name, usually used to identify the group in the form.
label String Question group label, usually displayed to the user.
questions Array List of questions in the group. See the Questions table below.
relevant String A reference to another field and corresponding value indicating when the field is displayed.

Questions

Property Type Description
id String The ID of the question.
name String Question name, usually used to identify fields in the form.
label String Question label, usually displayed to the user.
type String The field type, based on the question types available through XLSforms] . See the table below to see how they translate.
required Boolean Indicates whether the field is required.
constraint String The range of accepted values for the field. See XLSForms documentation for more information.
default String The default value of the field.
hint String An additional help text describing details of the field, usually displayed next to the field label.
relevant String A reference to another field and corresponding value indicating when the field is displayed.
options Array A list of choices, only relevant if type is select_one or select_multiple . See Options table below for more information.

Options

Property Type Required? Description
id String x The ID of the choice option.
name String x Choice name, usually as value for the form field.
label String x Choice label, usually displayed to the user.

type Options

Use this chart to figure out what type of question you're using in your form.

type XLSform Answer Input
IN integer Integer (i.e., whole number) input.
DE decimal Decimal input.
TX text Free text response.
S1 select_one Multiple choice question; only one answer can be selected.
SM select_multiple Multiple choice question; multiple answers can be selected.
NO note Display a note on the screen, takes no input.
GP geopoint Collect a single GPS coordinates.
GT geotrace Record a line of two or more GPS coordinates.
GS geoshape Record a polygon of multiple GPS coordinates; the last point is the same as the first point.
DA date Date input.
TI time Time input.
DT dateTime Accepts a date and a time input.
PH image / photo Take a picture.
AU audio Take an audio recording.
VI video Take a video recording.
BC barcode Scan a barcode, requires the barcode scanner app to be installed.
CA calculate Perform a calculation; see the Calculation section below.
AC acknowledge Acknowledge prompt that sets value to “OK” if selected.

The following values are for metadata that your questionnaire may be collecting:

type XLSform Answer Input
ST start Indicates the start of the survey.
EN end Indicates the end of the survey.
TD today Day of the survey.
DI deviceid IMEI (International Mobile Equipment Identity)
SI subscriberid IMSI (International Mobile Subscriber Identity)
SS simserial SIM serial number.
PN phonenumber Phone number of the device (if available)
Example Questionnaire JSON Payload
{
  "filename": "wa6hrqr4e4vcf49q6kxjc443",
  "id": "pignmhca2xgtpprcuw79fawb",
  "id_string": "wa6hrqr4e4vcf49q6kxjc443",
  "md5_hash": "0c359dabdbe5006c68c44438ccd86c1f",
  "question_groups": [
    {
      "id": "4x5nwwvs523cta83umn6ucc9",
      "index": 0,
      "label": "Tenure relationship attributes",
      "label_xlat": "Tenure relationship attributes",
      "name": "tenure_relationship_attributes",
      "question_groups": [],
      "questions": [
        {
          "constraint": null,
          "default": null,
          "hint": null,
          "id": "2tecu2qsjyihkk7acqwnpdhp",
          "index": 0,
          "label": "Notes",
          "label_xlat": "Notes",
          "name": "notes",
          "relevant": null,
          "required": false,
          "type": "TX"
        }
      ],
      "relevant": null,
      "type": "group"
    },{
      "id": "8y8hv2vmp25crcytqf4gcsk3",
      "index": 1,
      "label": "Default Party Attributes",
      "label_xlat": "Default Party Attributes",
      "name": "party_attributes_default",
      "question_groups": [],
      "questions": [
        {
          "constraint": null,
          "default": null,
          "hint": null,
          "id": "dsqj28xdx4m8wu3e8kstnwx7",
          "index": 0,
          "label": "Notes",
          "label_xlat": "Notes",
          "name": "notes",
          "relevant": null,
          "required": false,
          "type": "TX"
        }
      ],
      "relevant": null,
      "type": "group"
    },{
      "id": "zu7wigmdketa7xnherh6295f",
      "index": 2,
      "label": "Location Attributes",
      "label_xlat": "Location Attributes",
      "name": "location_attributes",
      "question_groups": [],
      "questions": [
        {
          "constraint": null,
          "default": null,
          "hint": null,
          "id": "wy32hht8ckfrbh4btnk6tg55",
          "index": 0,
          "label": "Name of Location",
          "label_xlat": "Name of Location",
          "name": "name",
          "relevant": null,
          "required": false,
          "type": "TX"
        },{
          "constraint": null,
          "default": "null",
          "hint": "Quality of parcel geometry",
          "id": "bcivhzvawbznknrgz99mh55s",
          "index": 1,
          "label": "Spatial Unit Quality",
          "label_xlat": "Spatial Unit Quality",
          "name": "quality",
          "options": [
            {
              "id": "gfpftuhcz73wmifur248bh2u",
              "index": 1,
              "label": "No data",
              "label_xlat": "No data",
              "name": "null"
            },{
              "id": "hid7jsnun2twnnfscvkyx25w",
              "index": 2,
              "label": "Textual",
              "label_xlat": "Textual",
              "name": "text"
            },{
              "id": "5qssuz7ig5wzymb33d2rat2p",
              "index": 3,
              "label": "Point data",
              "label_xlat": "Point data",
              "name": "point"
            },{
              "id": "pb8rsyum45hrvwasebmzernb",
              "index": 4,
              "label": "Low quality polygon",
              "label_xlat": "Low quality polygon",
              "name": "polygon_low"
            },{
              "id": "9pb2uthpy7w44f9yq4vrmgcm",
              "index": 5,
              "label": "High quality polygon",
              "label_xlat": "High quality polygon",
              "name": "polygon_high"
            }
          ],
          "relevant": null,
          "required": false,
          "type": "S1"
        },{
          "constraint": null,
          "default": "OT",
          "hint": null,
          "id": "easzuvr9vyqspai2jg9hcusa",
          "index": 2,
          "label": "How was this location acquired?",
          "label_xlat": "How was this location acquired?",
          "name": "acquired_how",
          "options": [
            {
              "id": "3y4j9d35pcy7dnkpmzspd4hz",
              "index": 1,
              "label": "Contractual Share Crop",
              "label_xlat": "Contractual Share Crop",
              "name": "CS"
            },{
              "id": "hy95hvwvgidx8av7tv5e2va2",
              "index": 2,
              "label": "Customary Arrangement",
              "label_xlat": "Customary Arrangement",
              "name": "CA"
            },{
              "id": "88i4xdyg9qufm89biarqhcf3",
              "index": 3,
              "label": "Gift",
              "label_xlat": "Gift",
              "name": "GF"
            }
          ],
          "relevant": null,
          "required": false,
          "type": "S1"
        },{
          "constraint": null,
          "default": "null",
          "hint": null,
          "id": "ckargaqthq4gby7f3u5ywd2f",
          "index": 3,
          "label": "When was this location acquired?",
          "label_xlat": "When was this location acquired?",
          "name": "acquired_when",
          "relevant": null,
          "required": false,
          "type": "DA"
        },{
          "constraint": null,
          "default": null,
          "hint": "Additional Notes",
          "id": "557mb6s7sv5k8dhcvcqsugc7",
          "index": 4,
          "label": "Notes",
          "label_xlat": "Notes",
          "name": "notes",
          "relevant": null,
          "required": false,
          "type": "TX"
        }
      ],
      "relevant": null,
      "type": "group"
    }
  ],
  "questions": [
    {
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "ybqnrd3qbg2a3if75p4ybcda",
      "index": 3,
      "label": "Start",
      "label_xlat": "Start",
      "name": "start",
      "relevant": null,
      "required": false,
      "type": "ST"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "d28dw58n6n6ptigkyjcqzqfm",
      "index": 4,
      "label": "End",
      "label_xlat": "End",
      "name": "end",
      "relevant": null,
      "required": false,
      "type": "EN"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "vmgdx4mtsuy2tssvc923naat",
      "index": 5,
      "label": "Today",
      "label_xlat": "Today",
      "name": "today",
      "relevant": null,
      "required": false,
      "type": "TD"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "ygzf4z769ry28dpfmvnttacm",
      "index": 6,
      "label": "DeviceId",
      "label_xlat": "DeviceId",
      "name": "deviceid",
      "relevant": null,
      "required": false,
      "type": "DI"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "w3ihrqpq9pv4g754p68nd4y3",
      "index": 7,
      "label": "Cadasta Platform - UAT Survey",
      "label_xlat": "Cadasta Platform - UAT Survey",
      "name": "title",
      "relevant": null,
      "required": false,
      "type": "NO"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "njksjf6sy8imsqhsu5twbdt6",
      "index": 8,
      "label": "Party Classification",
      "label_xlat": "Party Classification",
      "name": "party_type",
      "options": [
        {
          "id": "qzaxe9jx5sym69vqxxj2z6s8",
          "index": 1,
          "label": "Group",
          "label_xlat": "Group",
          "name": "GR"
        },{
          "id": "4afq8wfhv93czkveb43chqpq",
          "index": 2,
          "label": "Individual",
          "label_xlat": "Individual",
          "name": "IN"
        },{
          "id": "9ew3kquph5nw4v4xaccyx7xq",
          "index": 3,
          "label": "Corporation",
          "label_xlat": "Corporation",
          "name": "CO"
        }
      ],
      "relevant": null,
      "required": true,
      "type": "S1"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "szdxshbt6hq9f2qpyff4aq6s",
      "index": 9,
      "label": "Party Name",
      "label_xlat": "Party Name",
      "name": "party_name",
      "relevant": null,
      "required": true,
      "type": "TX"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "tr42se28bs44m92uc6xtpb9q",
      "index": 10,
      "label": "Location of Parcel",
      "label_xlat": "Location of Parcel",
      "name": "location_geometry",
      "relevant": null,
      "required": false,
      "type": "GT"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "sg8x3ggnuwn8ci6frgc9jmw4",
      "index": 11,
      "label": "What is the land feature?",
      "label_xlat": "What is the land feature?",
      "name": "location_type",
      "options": [
        {
          "id": "32ks5s69uj7t84ydcniyg5wd",
          "index": 1,
          "label": "Parcel",
          "label_xlat": "Parcel",
          "name": "PA"
        },{
          "id": "8z5qq8dtsjtvxgd445ei4rc7",
          "index": 2,
          "label": "Community Boundary",
          "label_xlat": "Community Boundary",
          "name": "CB"
        },{
          "id": "ksj3qsxmud8xe67b78pnyri7",
          "index": 3,
          "label": "Building",
          "label_xlat": "Building",
          "name": "BU"
        }
      ],
      "relevant": null,
      "required": true,
      "type": "S1"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "umxciy3sz28j379qkxmngjyv",
      "index": 12,
      "label": "Photo of Parcel?",
      "label_xlat": "Photo of Parcel?",
      "name": "location_photo",
      "relevant": null,
      "required": false,
      "type": "PH"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "as4tw2yf8bpm7grfxjyxwhf6",
      "index": 13,
      "label": "Photo of Party?",
      "label_xlat": "Photo of Party?",
      "name": "party_photo",
      "relevant": null,
      "required": false,
      "type": "PH"
    },{
      "constraint": null,
      "default": null,
      "hint": null,
      "id": "qwythvtbuech8fgirt3fqapa",
      "index": 14,
      "label": "What is the social tenure type?",
      "label_xlat": "What is the social tenure type?",
      "name": "tenure_type",
      "options": [
        {
          "id": "7jxjinrf56vudyfnyuwdytg2",
          "index": 1,
          "label": "All Types",
          "label_xlat": "All Types",
          "name": "AL"
        },{
          "id": "7yjd2yqnmdku52em9sst3sck",
          "index": 2,
          "label": "Carbon Rights",
          "label_xlat": "Carbon Rights",
          "name": "CR"
        },{
          "id": "37ewegjhj4duvrgqw5erzrnz",
          "index": 3,
          "label": "Concessionary Rights",
          "label_xlat": "Concessionary Rights",
          "name": "CO"
        }
      ],
      "relevant": null,
      "required": true,
      "type": "S1"
    }
  ],
  "title": "wa6hrqr4e4vcf49q6kxjc443",
  "version": 2017011815055872,
  "xls_form": ""
}

Get the Project's Current Questionnaire

Returns the projects current questionnaire structure.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Response

The response body contains a full questionnaire JSON object, including questions and question groups.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/questionnaire/

Replace the Project's Current Questionnaire

This method creates a new questionnaire for the project. Questionnaires are either created by providing a link to a XLSForm or by providing a valid Questionnaire JSON object.

Note: At the moment, updating the questionnaire is only possible as long as no data has been contributed to the project. If you need to change your questionnaire, you need to create a new project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Request Payload: XLS Form Replacement

The request payload is a JSON object containing the following properties.

Property Description
xls_form A link to a XLSForm stored on an accessible server.

Request Payload: Replacement by JSON Object

Creating a questionnaire from a JSON object requires a full questionnaire JSON object provided with the request payload.

Response

The response body contains a full questionnaire JSON object, including questions and question groups.

PUT
/api/v1/organizations/{organization_slug}/projects/{project_slug}/questionnaire/

This feature is still being developed. Documentation to be completed when it's done.

Spatial Units (a.k.a Locations)

Projects on the Cadasta Platform are spatial in nature – collections of points, lines, and/or polygons representing areas where land rights documentation is happening. These points, lines, and polygons can be retrieved and modified using the Cadasta API.

Read more about Project Locations in our Platform Documentation

The endpoint spatial units, or locations, start like this: /api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/

Spatial Unit JSON Object

A spatial unit/location JSON object is a GEOJSON object containing the following properties:

Property Type Description
type String This field is automatically set to Feature .
geometry Object A GeoJSON representation of the spatial unit's geometry.
properties Object An object that gives the location a unique ID, defines the type of location it is (land types ), and lists any attributes. (See the properties table below for more information)

The properties object contains the following properties:

Property Type Description
id String A unique ID for the spatial unit
type String The type of spatial unit that it is, defined by the fields in your questionnaire. (See the land types table below )
attributes Object Project-specific attributes that are defined through the projects questionnaire.

Land type Abbreviations

The choices, or land types, for location types can be custom values. For all choice values, the names must be 10 characters or less, while the labels do not have any limitations.

In the past, many projects have used these abbreviations for land types:

Abbreviation What it Represents
PA Parcel
CB Community Boundary
BU Building
AP Apartment
PX Project Extent
RW Right-of-way
NP National Park Boundary
MI Miscellaneous

Example Spatial Unit/Location JSON Object

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -122.66475677490233,
          45.50045162361647
        ],
        [
          -122.66956329345703,
          45.487395598055215
        ],
        [
          -122.66252517700195,
          45.49954923075264
        ],
        [
          -122.66475677490233,
          45.50045162361647
        ]
      ]
    ]
  },
  "properties": {
    "id": "39jvd8r93jijahnvgd4s4cih",
    "type": "PA",
    "attributes": {},
    "project": {
      "id": "hxk4k8aee5rh5htahhh5uenn",
      "organization": {
        "id": "gae6pjf9xygxddgyg5dq45iq",
        "slug": "example-organization",
        "name": "Example Organization"
      },
      "name": "Portland Project",
      "slug": "portland-project"
    }
  }
}

List Spatial Units/Locations

Use this method to get a list of all spatial units in a project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Response

The response body is a GeoJSON feature collection of multiple project location / spatial unit JSON objects, but without the project property.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.7457809448242,
                45.64344809984393
              ],[
                -122.7308464050293,
                45.640807770704704
              ],[
                -122.74543762207031,
                45.64068775278732
              ],[
                -122.7457809448242,
                45.64344809984393
              ]
            ]
          ]
        },
        "properties": {
          "id": "xtc4de68iawwzgtawp8avgv8",
          "type": "PA",
          "attributes": {}
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.66475677490233,
                45.50045162361647
              ],[
                -122.66956329345703,
                45.487395598055215
              ],[
                -122.66252517700195,
                45.49954923075264
              ],[
                -122.66475677490233,
                45.50045162361647
              ]
            ]
          ]
        },
        "properties": {
          "id": "39jvd8r93jijahnvgd4s4cih",
          "type": "PA",
          "attributes": {}
        }
      }
    ]
  }
}

Create a New Spatial Unit/Location

Use this method to create a new spatial unit/location.

Request Payload

Property Type Required? Description
geometry Object x A GeoJSON geometry ) defining the geographic coordinates of the location.
type String x This refers to the possible land types that the location could be (e.g. PA = Parcel). See the Land type Abbreviations table above for more information.
attributes Array An array of different attributes for the property.

Response

The response is a complete spatial unit/location JSON Object.

POST
/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/

Example Response

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      -122.7457809448242,
      45.64344809984393
    ]
  },
  "properties": {
    "id": "n776cwdhqriaqdwsfafiajib",
    "type": "MI",
    "attributes": {}
  }
}

Get a Spatial Unit/Location

Use this method to get the JSON object for a specific spatial unit/location.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
spatial_unit_id The uniqe ID of the spatial unit, which you can find by listing all of the spatial units for the project it's in.

Response

The response is a complete spatial unit/location JSON Object.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/{spatial_unit_id}/

Example Response

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -122.66475677490233,
          45.50045162361647
        ],
        [
          -122.66956329345703,
          45.487395598055215
        ],
        [
          -122.66252517700195,
          45.49954923075264
        ],
        [
          -122.66475677490233,
          45.50045162361647
        ]
      ]
    ]
  },
  "properties": {
    "id": "39jvd8r93jijahnvgd4s4cih",
    "type": "PA",
    "attributes": {}
  }
}

Update a Spatial Unit/Location

Use this method to update the JSON object for a specific spatial unit/location.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
spatial_unit_id The unique ID of the spatial unit, which you can find by listing all of the spatial units for the project it's in.

Request Payload

Property Type Required? Description
geometry Object x A GeoJSON geometry defining the geographic coordinates of the location.
type String x This refers to the possible land types that the location could be (e.g. PA = Parcel). See the land types table above for more information.
attributes Object An array of different attributes for the property.

Response

The response is a complete spatial unit/location JSON Object.

PATCH
/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/{spatial_unit_id}/

Example Response

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -122.7457809448242,
          45.64344809984393
        ],
        [
          -122.7457809448235,
          45.64344809984442
        ],
        [
          -122.7457809448219,
          45.64344809984999
        ],
        [
          -122.7457809448242,
          45.64344809984393
        ]
      ]
    ]
  },
  "properties": {
    "id": "w4rwh32mqctn9g223wnry2gx",
    "type": "PA",
    "attributes": {}
  }
}

Delete a Spatial Unit/Location

Use this method to delete a spatial unit/location.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
spatial_unit_id The unique ID of the spatial unit, which you can find by listing all of the spatial units for the project it's in.

Response

If the spatial unit was successfully deleted, an empty response with status code 204 is returned.

DELETE
/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/{spatial_unit_id}/

Parties

Each project location has a relationship with people of all kinds – sometimes individuals, sometimes groups, and sometimes a corporation. These people are known as parties in the Cadasta system.

Read more about Parties in our Platform Documentation

Using the API, you can view, create, update, and delete parties for your project.

The endpoint for parties begins like this: /api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/

Party JSON object

A party JSON object contains the following properties:

Property Type Description
id String The auto-generated unique ID for each party.
name String The name of the party.
type String The type of party, indicating whether it's an individual ( IN ), a group ( GR ), or a corporation ( CO ).
attributes Object Project-specific attributes that are defined through the projects questionnaire.

Example Party JSON Object

{
  "id": "z8f83bt6fskq6wcvnp223t3q",
  "name": "Jane Doe",
  "type": "IN",
  "attributes": {}
}

List Parties

Use this method to return all of the parties listed as part of a project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Response

The response is an array of party JSON objects without the project property.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "ajnyj54mpma7kpexxejfv5he",
      "name": "Example Corp.",
      "type": "CO",
      "attributes": {}
    },
    {
      "id": "cnpsvntqugkncywqevhznnsz",
      "name": "Elizabeth James",
      "type": "IN",
      "attributes": {}
    },
    {
      "id": "wvvi6sbgdf77nfwbe26fgz3z",
      "name": "Portland Islands Neighborhood Association",
      "type": "GR",
      "attributes": {}
    }
  ]
}

Create a New Party

Use this method to create a new party.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Request Payload

Property Type Required? Description
name CharField x The name of the party.
type ChoiceField x The type of party, indicating whether it's an individual ( IN ), a group ( GR ), or a corporation ( CO ).
attributes Object Project-specific attributes that are defined through the projects questionnaire.

Response

The response is a party JSON object.

POST
/api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/

Example Response

{
  "id": "z8f83bt6fskq6wcvnp223t3q",
  "name": "Jane Doe",
  "type": "IN",
  "attributes": {}
}

Get a Party

Use this method to get at a specific party.

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
party_id The unique ID generated for the specific party, which can be found by listing all of the parties .

Response

The response contains a party JSON object.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/{party_id}/

Example Response

{
  "id": "z8f83bt6fskq6wcvnp223t3q",
  "name": "Jane Doe",
  "type": "IN",
  "attributes": {}
}

Update a Party

Use this method to update the name, type, or attributes of a party.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
party_id The unique ID generated for the specific party, which can be found by listing all of the parties .

Request Payload

You can modify any one of these fields:

Property Type Required? Description
name String The name of the party.
type String The type of party, indicating whether it's an individual ( IN ), a group ( GR ), or a corporation ( CO ).
attributes Object Project-specific attributes that are defined through the projects questionnaire.

Response

The response contains a party JSON object.

PATCH
/api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/{party_id}/

Example Response

{
  "id": "z8f83bt6fskq6wcvnp223t3q",
  "name": "Jane Doe",
  "type": "IN",
  "attributes": {}
}

Delete a Party

Use this method and endpoint to delete a party.

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
party_id The unique ID generated for the specific party, which can be found by listing all of the parties .

Response

If the party was successfully deleted, an empty response with status code 204 is returned.

DELETE
/api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/{party_id}/

Relationships

Each location has a relationship with one or more parties, and each of those parties has a specific type of relationship with the land. For example, a municipal body may own a park, and a local tribe may have right-of-way access to it. Ownership and right-of-way-access are both types of relationships. (Note that sometimes you may also see the word "tenure" in lieu of or alongside the word "relationship.")

Read more about Relationships in our Platform Documentation

The Cadasta API allows you to list relationships of a party and list relationships to a spatial unit/location. You can also get, create, update, and delete relationships as well.

Endpoints in this section start with:

/api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/{party_id}/relationships/

or

/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/{spatial_unit_id}/relationships/

or

/api/v1/organizations/{organization_slug}/projects/{project_slug}/relationships/tenure/{relationship_id}/

Relationship JSON object

A relationship object contains the following properties:

Property Type Description
rel_class String The type of relationships; currently "tenure" is the only possible relationship type.
id String The unique ID of the relationship
party Array The object containing the party that the spatial unit is related to. (See the party table below for more information.)
spatial_unit Object The spatial unit/location object. (See the spatial unit table below for more information.)
tenure_type String The kind of relationship. (See the Relationship (Tenure) Categories table for more information.)
attributes Object Project-specific attributes that are defined through the project's questionnaire.

The party object has the following properties:

Property Type Description
id String The unique ID of the party.
name String The name of the party.
type String The type of party, e.g. an individual ( IN ), a group ( GR ), or a corporation ( CO ).

The spatial_unit object has the following properties:

Property Type Description
type String Type of spatial unit; automatically set to Feature .
geometry Object A GeoJSON representation of the spatial unit's geometry.
properties Object An object that gives the location a unique ID and defines the type of location it is (land types ). (See the properties table below for more information)

Relationship (Tenure) Categories

Relationships fall into one of the following categories. The abbreviations on the left are what you'd use when modifying or reading a relationship using the API:

Abbreviation What it Represents
AL All Types
CR Carbon Rights
CO Concessionary Rights
CU Customary Rights
EA Easement
ES Equitable Servitude
FH Freehold
GR Grazing Rights
HR Hunting/Fishing/Harvest Rights
IN Indigenous Land Rights
JT Joint Tenancy
LH Leasehold
LL Longterm leasehold
MR Mineral Rights
OC Occupancy (No Documented Rights)
TN Tenancy (Documented Sub-lease)
TC Tenancy in Common
UC Undivided Co-ownership
WR Water Rights

Example Relationship JSON Object

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "rel_class": "tenure",
      "id": "mmikx24rcjd2stgyqz495fqa",
      "party": {
        "id": "wvvi6sbgdf77nfwbe26fgz3z",
        "name": "Portland Islands Neighborhood Association",
        "type": "GR"
      },
      "spatial_unit": {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.7457809448242,
                45.64344809984393
              ],
              [
                -122.7308464050293,
                45.640807770704704
              ],
              [
                -122.74543762207031,
                45.64068775278732
              ],
              [
                -122.7457809448242,
                45.64344809984393
              ]
            ]
          ]
        },
        "properties": {
          "id": "xtc4de68iawwzgtawp8avgv8",
          "type": "PA"
        }
      },
      "tenure_type": "TN",
      "attributes": {}
    }
  ]
}

List Relationships

Relationships are defined between a party and a spatial unit. You can list existing relationships connected to a party or to a spatial unit.

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
party_id Only required when listing relationships to a party. The unique ID generated for the specific party, which can be found by listing all of the parties .
spatial_unit_id Only required when listing relationships to a spatial unit. The unique ID generated for the specific spatial unit, which can be found by listing all of the spatial units .

Response

The response contains a list of relationship JSON objects.

List relationships to a party

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/parties/{party_id}/relationships/

List relationships to a spatial unit

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatial/{spatial_unit_id}/relationships/

Example Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "rel_class": "tenure",
      "id": "mmikx24rcjd2stgyqz495fqa",
      "party": {
        "id": "wvvi6sbgdf77nfwbe26fgz3z",
        "name": "Portland Islands Neighborhood Association",
        "type": "GR"
      },
      "spatial_unit": {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.7457809448242,
                45.64344809984393
              ],
              [
                -122.7308464050293,
                45.640807770704704
              ],
              [
                -122.74543762207031,
                45.64068775278732
              ],
              [
                -122.7457809448242,
                45.64344809984393
              ]
            ]
          ]
        },
        "properties": {
          "id": "xtc4de68iawwzgtawp8avgv8",
          "type": "PA"
        }
      },
      "tenure_type": "TN",
      "attributes": {}
    },
    {
      "rel_class": "tenure",
      "id": "f2eq96ez7rnkucwz9sr4my9y",
      "party": {
        "id": "ajnyj54mpma7kpexxejfv5he",
        "name": "Example Corp.",
        "type": "CO"
      },
      "spatial_unit": {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.7457809448242,
                45.64344809984393
              ],
              [
                -122.7308464050293,
                45.640807770704704
              ],
              [
                -122.74543762207031,
                45.64068775278732
              ],
              [
                -122.7457809448242,
                45.64344809984393
              ]
            ]
          ]
        },
        "properties": {
          "id": "xtc4de68iawwzgtawp8avgv8",
          "type": "PA"
        }
      },
      "tenure_type": "LL",
      "attributes": {}
    },
    {
      "rel_class": "tenure",
      "id": "5ueeskcsfgf4iuwcgmji3dik",
      "party": {
        "id": "cnpsvntqugkncywqevhznnsz",
        "name": "Joan Arches",
        "type": "IN"
      },
      "spatial_unit": {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.7457809448242,
                45.64344809984393
              ],
              [
                -122.7308464050293,
                45.640807770704704
              ],
              [
                -122.74543762207031,
                45.64068775278732
              ],
              [
                -122.7457809448242,
                45.64344809984393
              ]
            ]
          ]
        },
        "properties": {
          "id": "xtc4de68iawwzgtawp8avgv8",
          "type": "PA"
        }
      },
      "tenure_type": "WR",
      "attributes": {}
    }
  ]
}

Create a New Relationship

This section is still in progress.

Request Payload

Property Type Required? Description
party String x The ID of the party connected to the new relationship.
spatial_unit String x The ID of the spatial connected to the new relationship.
tenure_type String x The tenure relationship category.
attributes Object x Project-specific attributes that are defined through the project's questionnaire.

Response

The response contains a relationship JSON object.

POST
/api/v1/organizations/{organization_slug}/projects/{project_slug}/relationships/tenure/

Example Response

{
  "rel_class": "tenure",
  "id": "f2eq96ez7rnkucwz9sr4my9y",
  "party": {
    "id": "ajnyj54mpma7kpexxejfv5he",
    "name": "Example Corp.",
    "type": "CO"
  },
  "spatial_unit": {
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -122.7457809448242,
            45.64344809984393
          ],
          [
            -122.7308464050293,
            45.640807770704704
          ],
          [
            -122.74543762207031,
            45.64068775278732
          ],
          [
            -122.7457809448242,
            45.64344809984393
          ]
        ]
      ]
    },
    "properties": {
      "id": "xtc4de68iawwzgtawp8avgv8",
      "type": "PA"
    }
  },
  "tenure_type": "LL",
  "attributes": {}
}

Get a Relationship

Use this method and endpoint to get a specific relationship.

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
relationship_id The unique ID of the relationship, which can be found by listing all of the relationships to a spatial unit .

Response

The response contains a relationship JSON object.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/relationships/tenure/{relationship_id}/

Example Response

{
  "rel_class": "tenure",
  "id": "f2eq96ez7rnkucwz9sr4my9y",
  "party": {
    "id": "ajnyj54mpma7kpexxejfv5he",
    "name": "Example Corp.",
    "type": "CO"
  },
  "spatial_unit": {
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -122.7457809448242,
            45.64344809984393
          ],
          [
            -122.7308464050293,
            45.640807770704704
          ],
          [
            -122.74543762207031,
            45.64068775278732
          ],
          [
            -122.7457809448242,
            45.64344809984393
          ]
        ]
      ]
    },
    "properties": {
      "id": "xtc4de68iawwzgtawp8avgv8",
      "type": "PA"
    }
  },
  "tenure_type": "LL",
  "attributes": {}
}

Update a Relationship

Use this method and endpoint to update a relationship.

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
relationship_id The unique ID of the relationship, which can be found by listing all of the relationships to a spatial unit .

Request Payload

Property Type Required? Description
tenure_type String The relationship type; see Relationship (Tenure) Categories for an overview of accepted values.
attributes Object Project-specific attributes that are defined through the projects questionnaire.

Response

The response contains a relationship JSON object.

PATCH
/api/v1/organizations/{organization_slug}/projects/{project_slug}/relationships/tenure/{relationship_id}/

Example Response

{
  "rel_class": "tenure",
  "id": "f2eq96ez7rnkucwz9sr4my9y",
  "party": {
    "id": "ajnyj54mpma7kpexxejfv5he",
    "name": "Example Corp.",
    "type": "CO"
  },
  "spatial_unit": {
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -122.7457809448242,
            45.64344809984393
          ],
          [
            -122.7308464050293,
            45.640807770704704
          ],
          [
            -122.74543762207031,
            45.64068775278732
          ],
          [
            -122.7457809448242,
            45.64344809984393
          ]
        ]
      ]
    },
    "properties": {
      "id": "xtc4de68iawwzgtawp8avgv8",
      "type": "PA"
    }
  },
  "tenure_type": "LL",
  "attributes": {}
}

Delete a Relationship

Use this method to delete a relationship from a project.

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations .
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
relationship_id The unique ID of the relationship, which can be found by listing all of the relationships to a spatial unit .

Response

If the relationship was successfully deleted, an empty response with status code 204 is returned.

DELETE
/api/v1/organizations/{organization_slug}/projects/{project_slug}/relationships/tenure/{relationship_id}/

Project Resources

Each project has the ability to attach resources generally to projects or specifically to location, party or relationship entities. Resources may include letters, deeds/titles, photographs, audio recordings, etc. With the Cadasta API, you can list all the resources connected to a specific project, as well as create, view, and update individual ones.

Read more about Project Resources in our Platform Documentation

To access project resources using the API, use the following endpoint:

/api/v1/organizations/{organization_slug}/projects/{project_slug}/resources/

Project Resource Object

Each project resource appears as a JSON object with the following properties:

Property Type Description
id String A unique ID automatically generated for the file.
name String The name of the file (e.g. Deed of Trust)
description String A description of the file (e.g. The only deed we can find that has information relevant to the site.)
file String URL to a hosted version of the file, likely on an Amazon server or something similar.
original_file String Original file name (e.g. deed-of-trust.pdf).
archived Boolean Indicates whether the file has been archived or not.

Example Project Resource JSON Object

{
  "id": "8u5dgnvgzix6kmg9hvbfdy3c",
  "name": "Deed",
  "description": "",
  "file": "https://example.com/resources/wcajeysz7ngrae3bd84af99q.pdf",
  "original_file": "Deed-of-Trust-1912.pdf",
  "archived": false
}

List Project Resources

Use this method and endpoint to list out all the resources associated with any given project.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Response

The response body is an array containing a series of project resource JSON objects.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/resources/

Example Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "8u5dgnvgzix6kmg9hvbfdy3c",
      "name": "Deed",
      "description": "",
      "file": "https://example.com/resources/wcajeysz7ngrae3bd84af99q.pdf",
      "original_file": "Deed-of-Trust-1912.pdf",
      "archived": false
    },
    {
      "id": "xnbqgubg99x6w54q363tjx5d",
      "name": "Ross Island - 1963",
      "description": "",
      "file": "https://example.com/resources/tab6kkdfx9c5pifzsmmh4iep.jpg",
      "original_file": "a2004-001-1012-marquam-bridge-under-construction-1963.jpg",
      "archived": false
    },
    {
      "id": "p5d2wb5xnj4bn93vve8ntzwc",
      "name": "Ross Island Aerial - 1945",
      "description": "",
      "file": "https://example.com/resources/acguba29wstyexf8uhxkvezn.jpg",
      "original_file": "a2005-001-815-ross-island-bridge-west-approach-north-at-sw-kelly-1945.jpg",
      "archived": false
    }
  ]
}

Create a New Project Resource

Use this endpoint and method to create a new project resource.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .

Request Payload

To create a new resource, you'll need to provide the following properties:

Property Type Required? Description
name String x The name of the file (e.g. Deed of Trust)
description String A description of the file (e.g. The only deed we can find that has information relevant to the site.)
file String x URL to a hosted version of the file, likely on an Amazon server or something similar.
original_file String x Original file name (e.g. deed-of-trust.pdf).
archived Boolean x Indicates whether the file has been archived or not.

Response

The response body contains a project resource JSON object.

POST
/api/v1/organizations/{organization_slug}/projects/{project_slug}/resources/

Example Response

{
  "id": "rtxixdb2a5weefmzmg7kzvgr",
  "name": "Original Questionnaire",
  "description": "This is the original questionnaire we were using; we updated it on 10.31.2016.",
  "file": "https://example.com/minimum_cadasta_questionnaire.xlsx",
  "original_file": "mimimum_cadasta_questionnaire.xlsx",
  "archived": false
}

Get a Project Resource

Use this method and endpoint to get a specific project resource.

URL Parameters

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
resource_id The unique ID for the project resource. You can find this resource by listing all of the resources for the project , finding the project you're looking for, and then copying the ID.

Response

The response body contains a project resource JSON object.

GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/resources/{resource_id}/

Example Response

{
  "id": "rtxixdb2a5weefmzmg7kzvgr",
  "name": "Original Questionnaire",
  "description": "This is the original questionnaire we were using; we updated it on 10.31.2016.",
  "file": "https://example.com/minimum_cadasta_questionnaire.xlsx",
  "original_file": "mimimum_cadasta_questionnaire.xlsx",
  "archived": false
}

Update a Project Resource

Use this method and endpoint to update the name, description, file, original file name, and archive status of any resource.

URL Parameter

URL Parameter Description
organization_slug The slug provided for the organization, which can be found by locating the organization in the list of all organizations
project_slug The slug provided for the project, which can be found by listing all of the projects in an organization .
resource_id The unique ID for the project resource. You can find this resource by listing all of the resources for the project , finding the project you're looking for, and then copying the ID.

Request Payload

Modify any value of the following fields of the project resource JSON object:

Property Type Description
name String The name of the file (e.g. Deed of Trust)
description String A description of the file (e.g. The only deed we can find that has information relevant to the site.)
file String URL to a hosted version of the file, likely on an Amazon server or something similar.
original_file String Original file name (e.g. deed-of-trust.pdf).
archived Boolean Indicates whether the file has been archived or not.

Response

The response body contains a project resource JSON object.

PATCH
/api/v1/organizations/{organization_slug}/projects/{project_slug}/resources/{resource_id}/

Example Response

{
  "id": "rtxixdb2a5weefmzmg7kzvgr",
  "name": "Original Questionnaire",
  "description": "This is the original questionnaire we were using; we updated it on 10.31.2016.",
  "file": "https://example.com/minimum_cadasta_questionnaire.xlsx",
  "original_file": "mimimum_cadasta_questionnaire.xlsx",
  "archived": false
}

Spatial Resources

Sometimes your resources may be in the form of an XML file (usually converted from a GPS Exchange Format, or .gpx). You can use this API to return all of the GPS coordinates logged in the file.

Spatial resources can be accessed using endpoints that start like this:

/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatialresources/

List All Spatial Resources

Use this endpoint to return all of the spatial resources in a given project, along with the GPS coordinates in each resource.

Response

The response is an array of project resource JSON objects, each with an additional spatial_resources object field.

The spatial_resources object has the following properties:

Property Type Description
id String A unique ID automatically generated for the file.
name String The name of the file (e.g. Waypoints)
time String The date and time that the file was uploaded.
geom Array The object containing all of the geometric information in the spatial resource. (See the geom table below.)

The geom object has the following properties:

Property Type Description
geometries Array Contains an array of all the coordinates and type of coordinates for a particular spatial resource.
type String The type of coordinate collection (usually listed as GeometryCollection ). (See the geometries table below.)

The objects in geometries each have the following properties:

Property Type Description
coordinates Array Contains the latitude and longitude coordinates for each point.
type String The type of coordinate (usually set to Point ).
GET
/api/v1/organizations/{organization_slug}/projects/{project_slug}/spatialresources/

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "casjsraq9hmqaxkuh6scmue2",
      "name": "Waypoints",
      "description": "",
      "original_file": "Example (Waypoints_26-NOV-15).xml",
      "archived": false,
      "spatial_resources": [
        {
          "id": "ancghgmzbk8wi92fgt9yszdt",
          "name": "waypoints",
          "time": "2016-11-08T17:54:43.903091Z",
          "geom": {
            "geometries": [
              {
                "coordinates": [
                  3.35652,
                  6.464177
                ],
                "type": "Point"
              },
              {
                "coordinates": [
                  3.356425,
                  6.462206
                ],
                "type": "Point"
              },
              {
                "coordinates": [
                  3.35627,
                  6.46216
                ],
                "type": "Point"
              },
              {
                "coordinates": [
                  3.356593,
                  6.462282
                ],
                "type": "Point"
              }
            ],
            "type": "GeometryCollection"
          }
        }
      ]
    },
    {
      "id": "uqzbwpbeiyejfafx8t7nadcr",
      "name": "Waypoints 2",
      "description": "",
      "original_file": "Example 2 (Waypoints_26-NOV-15).xml",
      "archived": false,
      "spatial_resources": [
        {
          "id": "ryqfpbk6jmmrjshq7t7yguij",
          "name": "waypoints",
          "time": "2016-11-08T18:09:39.076667Z",
          "geom": {
            "geometries": [
              {
                "coordinates": [
                  4.35652,
                  7.464177
                ],
                "type": "Point"
              },
              {
                "coordinates": [
                  3.356389,
                  6.462436
                ],
                "type": "Point"
              },
              {
                "coordinates": [
                  4.356569,
                  7.462434
                ],
                "type": "Point"
              },
              {
                "coordinates": [
                  4.356593,
                  7.462282
                ],
                "type": "Point"
              }
            ],
            "type": "GeometryCollection"
          }
        }
      ]
    }
  ]
}
Cadasta API Documentation