NAV Navbar

Opendatasoft API Documentation

Introduction

API endpoint

https://mydomain.opendatasoft.com/api/management/v2

The Opendatasoft management API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors. If not otherwise specified, all parameters to GET calls are expected to be in the query string, and all parameters to calls made with other verbs are expected to be sent inside a JSON object in the body of the request.

General

Authentication

The management API supports API keys and basic auth for authentication.

API keys are recommended for any endpoint that supports them since they do not require using a user's password, which would provide unlimited access to the corresponding account if stolen. API keys are a way to mitigate this risk since they can be revoked easily and can be configured to provide only the necessary permissions for a given usage.

API key

Example authenticated request with an API key

curl https://mydomain.opendatasoft.com/api/management/v2/datasets?apikey=7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3

After being generated and given appropriate permissions with the corresponding endpoints, an API key can be used for every management API endpoint (unless specified in this documentation).

An API key must be passed with every authenticated request as the query parameter apikey.

Basic auth

Example authenticated request with Basic Auth

curl https://mydomain.opendatasoft.com/api/management/v2/datasets
  -u username:password

Basic auth credentials can be passed as the Authorization header, or via the authentication option any API client (e.g: curl, Postman, Python Requests, etc.) implements.

The Authorization field is constructed as follows (Wikipedia):

For example, if the user has Aladdin as the username and OpenSesame as the password, then the field's value is the base64-encoding of Aladdin:OpenSesame, or QWxhZGRpbjpPcGVuU2VzYW1l.

The Authorization header will appear as:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Please note that this header can easily be decoded back to the original username and password, so it must never be shared with anyone.

Errors

Example error

{
  "status_code": 404,
  "error_key": "UnknownUsernameException",
  "message": "Unknown username: toto",
  "raw_message": "Unknown username: {username}",
  "raw_params": {
    "username": "toto"
  }
}

All errors raised by the platform follow a common pattern. They will be rendered as an HTTP response with the proper HTTP status code (400, 404 etc.) and with a body describing the error.

Wrapped errors

{
  "status_code": 400,
  "error_key": "InvalidManagementAPIRequestException",
  "message": "Invalid management API request",
  "raw_message": "Invalid management API request",
  "raw_params": {},
  "errors": [
    ]
}

When updating a resource, you may get multiple errors because multiple properties of the object you provided in the payload have issues. In this case, these errors will be returned together, wrapped with a meta error.

Asynchronous calls

Example asynchronous request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXX/publish \
    -X PUT \
    -u username:password

Example response

{
  "job_id": "86a5eaf857201d3e11e67427b205121e7d19d77d"
}

While most API calls are synchronous, a few are not due to the impredictable nature of their execution time.

For example, publishing a dataset can be almost instantaneous but could also go on for hours depending on the size of the dataset and the complexity of the processing pipeline.

These calls will return instantaneously with a job identifier that you can then use to poll for a status update. Once the action is over, the poll's response will contain the action's response.

Expanding objects

Example non-expand request

curl http://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXX/security/users

Example response

[
  {
    "is_data_visible": true,
    "visible_fields": [],
    "filter_query": "",
    "api_calls_quota": null,
    "permissions": [
      "explore_restricted_dataset",
      "edit_dataset",
      "publish_dataset"
    ],
    "user": {
      "username": "myuser"
    }
  },
  {...},
  {...}
]

Example expand request

curl http://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXX/security/users?expand=user

Example response

[
  {
    "is_data_visible": true,
    "visible_fields": [],
    "filter_query": "",
    "api_calls_quota": null,
    "permissions": [
      "explore_restricted_dataset",
      "edit_dataset",
      "publish_dataset"
    ],
    "user": {
      "username": "myuser",
      "first_name": "First name",
      "last_name": "Last name",
      "email": "myuser@example.com",
      "is_active": true,
      "is_ods": false,
      "account_type": "global",
      "display_name": "myuser",
      "auth_provider_types": []
    }
  },
  {...},
  {...}
]

Many objects contain the identifier of a related object in their response properties. For example, a dataset security user ruleset will have an associated user. This object can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. This parameter is available on all API requests, and applies to the response of that request only.

Datetime objects

Example date

July 4th 2017, 11 hours 13 minutes and 53 seconds

2017-07-04T11:13:53

All datetime objects returned in this API are represented in ISO 8601, that is YYYY-MM-DDTHH:MM:SS. They are all UTC dates.

Required parameters

Unless explicity declared as optional, all API parameters are required.

Users

A user is a person who authentifies themself to utilize the platform.

Most of the times, users are invited on a domain via an e-mail:

In other words, user accounts are shared between all Opendatasoft domains, but a user must be linked to a specific domain via an invitation before being granted specific permissions on this domain.

Through the management API, it is possible to:

The User object

Example object

{
    "username": "louise.von-data",
    "first_name": "Louise",
    "last_name": "Von Data",
    "email": "louise.von-data@opendatasoft.com",
    "account_type": "global",
    "display_name": "louise.von-data",
    "auth_provider_types": [],
    "permissions": [
        "explore_restricted_dataset",
        "edit_dataset"
    ],
    "groups": [
        {
            "user_count": 1,
            "limits": {},
            "title": "Example Group",
            "quotas": {},
            "group_id": "example-group",
            "permissions": ["create_dataset"]
        }
    ],
    "is_active": true,
    "date_joined": "2018-05-02T09:36:30.531746+00:00",
    "limits": {},
    "is_ods": false,
    "quotas": {},
    "datasets_index_filters": [
        "publishing.published",
        "publishing.status",
        "visibility"
    ],
    "last_seen": "2018-05-03T12:51:50.250382+00:00"
}
Attribute Description
username
string
The user's username
first_name
string
The user's first name
last_name
string
The user's last name
email
string
The user's e-mail address
account_type
string
The user's account type.
Possible values are global, linked and local
display_name
string
The user's display name
simplified version of the username
auth_provider_types
array of string
The list of authentification providers type for this user.
Currently saml is the only available provider.
permissions
array
A list of permissions granted to this user
groups
array
A list of groups the user belongs to
is_active
boolean
True if the user can connect to their account
date_joined
date
The date when the user joined the domain
is_ods
boolean
True if the user belongs to the Opendatasoft organization
quotas
quotas object
An object holding the user's quotas on this domain
limits
limits object
An object holding the user's limits on this domain
datasets_index_filters
string
The user's filter preferences on the dataset index
last_seen
string
The date when the user used their account for the last time

List users

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/users/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/users/ \
    -u username:password

Example response

[
    {
        "username": "louise.von-data",
        "first_name": "Louise",
        "last_name": "Von Data",
        "email": "louise.von-data@opendatasoft.com",
        "account_type": "global",
        "display_name": "louise.von-data",
        "auth_provider_types": [],
        "permissions": [
            "explore_restricted_dataset",
            "edit_dataset"
        ],
        "groups": [
            {
                "user_count": 1,
                "limits": {},
                "title": "Example Group",
                "quotas": {},
                "group_id": "example-group",
                "permissions": ["create_dataset"]
            }
        ],
        "is_active": true,
        "date_joined": "2018-05-02T09:36:30.531746+00:00",
        "limits": {},
        "is_ods": false,
        "quotas": {},
        "datasets_index_filters": [
            "publishing.published",
            "publishing.status",
            "visibility"
        ],
        "last_seen": "2018-05-03T12:51:50.250382+00:00"
    },
    {...},
    {...}
]

This endpoint lists all the users linked to the domain.

Returns

Returns a list of User objects.

Invite users to the domain

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/users/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/users/ \
    -X POST \
    -u username:password \
    -d '{"emails": ["louise.von-data@opendatasoft.com", "bruce.von-data@opendatasoft.com"]}'

Example response (no error)

{
    "louise.von-data@opendatasoft.com": "success: louise.von-data",
    "bruce.von-data@opendatasoft.com": "success: bruce.von-data"
}

Example request (with errors)

curl http://yourdomain.opendatasoft.com/api/management/v2/users/ \
    -X POST \
    -u username:password
    -d '{"emails": ["louise.von-data@opendatasoft.com", "bruce.von-data"]}'

Example response (with errors)

{
    "bruce.von-data": "invalid-email",
    "louise.von-data@opendatasoft.com": "already-member"
}

Sends an invitation e-mail to a list of e-mail addresses.

Body

Parameter Description
emails
array
A list of e-mail addresses to invite on the domain

Returns

Returns a JSON object with requested e-mail addresses as keys and a status for the corresponding e-mail address as values.

Status Description
success: <username> The invitation was successfully sent, and the newly invited user will have <username> as a username. The mentioned username can either correspond to a user that already exists to a newly created user if they did not have an Opendatasoft account yet.
already-member The provided e-mail address corresponds to a user already linked to the domain
invalid-email The provided e-mail address is invalid
forbidden-email The provided e-mail address can not be invited on an Opendatasoft domain
license-users-exceeded The domain license does not allow to invite more users

Retrieve a user

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/users/<username>/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/users/louise.von-data/ \
    -u username:password

Example response

{
    "username": "louise.von-data",
    "first_name": "Louise",
    "last_name": "Von Data",
    "email": "louise.von-data@opendatasoft.com",
    "account_type": "global",
    "display_name": "louise.von-data",
    "auth_provider_types": [],
    "permissions": [
        "explore_restricted_dataset",
        "edit_dataset"
    ],
    "groups": [
        {
            "user_count": 1,
            "limits": {},
            "title": "Example Group",
            "quotas": {},
            "group_id": "example-group",
            "permissions": ["create_dataset"]
        }
    ],
    "is_active": true,
    "date_joined": "2018-05-02T09:36:30.531746+00:00",
    "limits": {},
    "is_ods": false,
    "quotas": {},
    "datasets_index_filters": [
        "publishing.published",
        "publishing.status",
        "visibility"
    ],
    "last_seen": "2018-05-03T12:51:50.250382+00:00"
}

This endpoint retrieves the requested user.

Returns

Returns a User object.

Update an user

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/users/<username>/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/users/louise.von-data/ \
    -X PUT \
    -u username:password \
    -d '{"group_ids": ["another-group"], "permissions": ["publish_dataset"]}'

Example response

{
    "username": "louise.von-data",
    "first_name": "Louise",
    "last_name": "Von Data",
    "email": "louise.von-data@opendatasoft.com",
    "account_type": "global",
    "display_name": "louise.von-data",
    "auth_provider_types": [],
    "permissions": [
        "publish_dataset"
    ],
    "groups": [
        {
            "user_count": 1,
            "limits": {},
            "title": "Another group",
            "quotas": {},
            "group_id": "another-group",
            "permissions": ["edit_page"]
        }
    ],
    "is_active": true,
    "date_joined": "2018-05-02T09:36:30.531746+00:00",
    "limits": {},
    "is_ods": false,
    "quotas": {},
    "datasets_index_filters": [
        "publishing.published",
        "publishing.status",
        "visibility"
    ],
    "last_seen": "2018-05-03T12:51:50.250382+00:00"
}

Update an existing user.

Body

Parameter Description
group_ids
array
optional A list of group identifiers to add the user to
permissions
array
optional A list of permissions to grant the user
quotas
quotas object
optional An object holding the quotas to grant the user
limits
limits object
optional An object holding the limits to grant the user

Returns

Returns a User object.

Remove a user from the domain

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/users/<username>/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/users/louise.von-data/ \
    -X DELETE \
    -u username:password

This endpoint removes the requested user from the domain.

Returns

On success the endpoint returns an empty 204 HTTP response. If the user is the only domain administrator left, the call will fail and an error specifying that a removal of the only domain administrator is unallowed will be returned.

Groups

A group is an entity comprising several users. When users are added to a group, they benefit from the permissions, quotas and limits of this group.

Through the management API, the following can be performed on the current domain:

The Group object

Example object

{
    "title": "My Users",
    "group_id": "my-users",
    "user_count": 1,
    "permissions": [
        "publish_dataset",
        "edit_dataset"
    ],
    "limits": {
        "max_records_by_dataset": 1000000,
        "max_datasets": 500
    },
    "quotas": {
        "limit": 1000,
        "unit": "day"
    }
}
Attribute Description
title
string
The group title
group_id
string
The group identifier
user_count
number
The count of users in the group
permissions
array
A list of permissions granted to these group members
quotas
quotas object
An object holding the group's quotas on this domain
limits
limits object
An object holding the group's limits on this domain

List groups

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/ \
    -u username:password

Example response

[
    {
        "title": "My Users",
        "group_id": "my-users",
        "user_count": 1,
        "permissions": [
            "publish_dataset",
            "edit_dataset"
        ],
        "limits": {
            "max_records_by_dataset": 1000000,
            "max_datasets": 500
        },
        "quotas": {
            "limit": 1000,
            "unit": "day"
        }
    },
    {...},
    {...}
]

This endpoint lists all the groups linked to the domain.

Returns

Returns a list of Group objects.

Create a group on the domain

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/ \
    -X POST \
    -u username:password \
    -d '{"title": "An API group"}'

Example response

{
    "user_count": 0,
    "limits": {},
    "title": "An API group",
    "quotas": {},
    "group_id": "an-api-group",
    "permissions": []
}

Creates a new empty group with a title on the domain.

Body

Parameter Description
title
string
The group title

Returns

Returns the newly created Group object.

Retrieve a group

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/<group_id>/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/my-users/ \
    -u username:password

Example response

{
    "title": "My Users",
    "group_id": "my-users",
    "user_count": 1,
    "permissions": [
        "publish_dataset",
        "edit_dataset"
    ],
    "limits": {
        "max_records_by_dataset": 1000000,
        "max_datasets": 500
    },
    "quotas": {
        "limit": 1000,
        "unit": "day"
    }
}

This endpoint retrieves the requested group.

Returns

Returns a Group object.

Update a group

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/<group_id>/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/my-users/ \
    -X PUT \
    -u username:password \
    -d '{"title": "My favorite users", "permissions": ["publish_dataset"]}'

Example response

{
    "title": "My favorite users",
    "group_id": "my-users",
    "user_count": 1,
    "permissions": [
        "publish_dataset"
    ],
    "limits": {
        "max_records_by_dataset": 1000000,
        "max_datasets": 500
    },
    "quotas": {
        "limit": 1000,
        "unit": "day"
    }
}

Update an existing group.

Body

Parameter Description
title
string
optional The group title
permissions
array
optional A list of permissions to grant the group
quotas
quotas object
optional An object holding the quotas to grant the group
limits
limits object
optional An object holding the limits to grant the group

Returns

Returns a Group object.

Delete a group

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/<group_id>/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/my-users/ \
    -X DELETE \
    -u username:password

Example response

{}

Delete a group.

Returns

Returns an empty object.

List users in a group

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/<group_id>/users/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/my-users/users/\
    -u username:password

Example response

{
    "users": [
        {
            "username": "louise.von-data",
            "first_name": "Louise",
            "last_name": "Von Data",
            "is_ods": false,
            "is_active": true,
            "email": null
        }
    ],
    "rows": 10,
    "page": 1,
    "nhits": 1
}

This endpoint lists all the users in a group.

Returns

Returns a paginated list of partial User objects (see The User object).

Add users in a group

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/<group_id>/users/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/my-users/users/ \
    -X POST \
    -u username:password \
    -d '{"usernames":["bruce.von-data", "louise.von-data"]}'

Example response

{
    "bruce.von-data": "success",
    "louise.von-data": "duplicate"
}

Adds a list of users (identified by their username) in a group.

Body

Parameter Description
usernames
array
A list of usernames that identify domain users

Returns

Returns a JSON object with requested usernames as keys and a status for the corresponding username as values.

Status Description
success The user was successfully added to the group
duplicate The user has not been added to the group because they were already a member
error The user has not been added to the group because of an error

Remove a user from a group

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/groups/<group_id>/users/<username>

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/groups/my-users/users/bruce.von-data \
    -X DELETE \
    -u username:password \

Removes a user from a group

Returns

Returns an empty response.

API keys

API keys are randomly generated passwords that can be used as an authentication method to access a protected API endpoint as an authorized user.

Through the management API, it is possible to list, create, lookup, update and delete API keys for one's own user.

The API key object

Example object

{
    "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
    "label": "My first API key",
    "permissions": [
        "edit_dataset",
        "explore_restricted_dataset"
    ]
}
Attribute Description
key
string
The API key
label
string
A label describing this key
permissions
array
The list of permissions granted to this API key

List API keys

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/apikeys/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/apikeys/ \
    -u username:password

Example response

[
    {
        "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
        "label": "My first API key",
        "permissions": [
            "edit_dataset",
            "explore_restricted_dataset"
        ]
    },
    {...},
    {...}
]

This endpoint lists all the API keys belonging to the user.

If the request is made with an API key, only this API key will be present in the response.

Returns

Returns a list of API keys objects.

Create an API key

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/apikeys/

Example request for an empty API key

curl https://yourdomain.opendatasoft.com/api/management/v2/apikeys/ \
    -X POST \
    -u username:password \
    -d '{}'

Example response for an empty API key

{
    "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
    "label": null,
    "permissions": [
        "explore_restricted_dataset"
    ]
}

Example request providing a label

curl http://yourdomain.opendatasoft.com/api/management/v2/apikeys/ \
    -X POST \
    -u username:password
    -d '{"label": "My own label"}'

Example response with the provided label

{
    "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
    "label": "My own label",
    "permissions": [
        "explore_restricted_dataset"
    ]
}

Example request providing a label and permissions

curl http://yourdomain.opendatasoft.com/api/management/v2/apikeys/ \
    -X POST \
    -u username:password \
    -d '{"label": "My own label", "permissions": ["edit_dataset", "publish_dataset"]}'

Example response with the provided label

{
    "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
    "label": "My own label",
    "permissions": [
        "edit_dataset",
        "publish_dataset"
    ]
}

Creates a new API key.

This endpoint can not be accessed with an API key.

Body

Parameter Description
label
string
optional A label describing this key
permissions
array
optional The list of permissions granted to this API key

Returns

Returns an API key object.

Retrieve an API key

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/apikeys/<KEY>

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/apikeys/7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3/ \
    -u username:password

Example response

{
    "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
    "label": "My first API key",
    "permissions": [
        "edit_dataset",
        "explore_restricted_dataset"
    ]
}

This endpoint retrieves the requested API key.

If the request is made with an API key, only this API key can be retrieved.

Returns

Returns an API key object.

Update an API key

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/apikeys/7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3/

Example request providing a label

curl http://yourdomain.opendatasoft.com/api/management/v2/apikeys/7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3/ \
    -X PUT \
    -u username:password \
    -d '{"label": "My own label"}'

Example response with the provided label

{
    "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
    "label": "My own label",
    "permissions": [
        "edit_dataset",
        "explore_restricted_dataset"
    ]
}

Example request providing a label and permissions

curl http://yourdomain.opendatasoft.com/api/management/v2/apikeys/7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3/ \
    -X PUT \
    -u username:password \
    -d '{"label": "My own label", "permissions": ["edit_dataset", "publish_dataset"]}'

Example response with the provided label

{
    "key": "7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3",
    "label": "My own label",
    "permissions": [
        "edit_dataset",
        "publish_dataset"
    ]
}

Example request for an empty API key (invalid)

curl https://yourdomain.opendatasoft.com/api/management/v2/apikeys/7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3/ \
    -X PUT \
    -u username:password \
    -d '{}'

Example response for an empty API key

{
    "status_code": 400,
    "message": "'permissions' or 'label' must be provided to update an API key",
    "raw_params": {},
    "raw_message": "'permissions' or 'label' must be provided to update an API key",
    "error_key": "PermissionsOrLabelMissingFromAPIKeyUpdateException"
}

Update an existing API key.

This endpoint can not be accessed with an API key.

Body

Parameter Description
label
string
optional A label describing this key
permissions
array
optional The list of permissions granted to this API key

Returns

Returns an API key object.

Delete an API key

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/apikeys/7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3/

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/apikeys/7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3/ \
    -X DELETE \
    -u username:password

Delete an existing API key.

This endpoint can not be accessed with an API key.

Returns

Returns an empty response (code: 204).

Permissions

Users, groups and API keys can bear permissions that grant users the right to access protected endpoints or perform restricted actions on a domain.

As API keys can never have more authorizations than their owner, permissions given to an API key must also be given to the user who owns the API key for them to be taken into account.

Available permissions

There are 3 kinds of permissions:

Domain level permissions

Permission Description
edit_domain Ability to edit the properties of the domain, including user and group management
create_page Ability to create new pages
edit_page Ability to edit all pages
manage_page Ability to change the security of any page editable by this user
explore_restricted_page Ability to browse any page, even the restricted ones
create_dataset Ability to create new datasets
edit_dataset Ability to edit all datasets
publish_dataset Ability to publish datasets editable by this user
manage_dataset Ability to change the security of datasets editable by this user
explore_restricted_dataset Ability to browse any dataset, even the restricted ones
edit_reuse  Ability to edit and manage existing reuses
manage_subdomains Ability to create and manage subdomains
explore_monitoring Ability to browse any monitoring dataset and access the analytics section of the back-office
edit_theme Ability to manage the domain's theme (edit and make live)

Dataset level permissions

Permission Description
edit_dataset Ability to edit this dataset
publish_dataset Ability to publish this dataset
manage_dataset Ability to change the security of this dataset
explore_restricted_dataset Ability to browse this dataset

Page level permissions

Permission Description
edit_page Ability to edit this page
manage_page Ability to change the security of this page
explore_restricted_page Ability to browse this page

Required permissions per endpoint

Dataset Index

GET /api/management/v2/datasets/

Requires one of the following:

Dataset Create

POST /api/management/v2/datasets/

Requires domain permission: create_dataset

Dataset Lookup

GET /api/management/v2/datasets/<dataset_uid>/

Requires one of the following:

Dataset Delete

DELETE /api/management/v2/datasets/<dataset_uid>/

Requires one of the following:

Dataset Abort Action

PUT /api/management/v2/datasets/<dataset_uid>/abort/

Requires one of the following:

Dataset Attachements Index

GET /api/management/v2/datasets/<dataset_uid>/attachments/

Requires one of the following:

Dataset Attachements Create

POST /api/management/v2/datasets/<dataset_uid>/attachments/

Requires one of the following:

Dataset Attachment Lookup

GET /api/management/v2/datasets/<dataset_uid>/attachments/<attachment_uid>/

Requires one of the following:

Dataset Attachment Delete

DELETE /api/management/v2/datasets/<dataset_uid>/attachments/<attachment_uid>/

Requires one of the following:

Dataset Change Index

GET /api/management/v2/datasets/<dataset_uid>/changes/

Requires one of the following:

Dataset Attachment Download

GET /api/management/v2/datasets/<dataset_uid>/download_attachment/<attachment_uid>

Requires one of the following:

Dataset System Processor Index

GET /api/management/v2/datasets/<dataset_uid>/fields_specifications/

Requires one of the following:

Dataset System Processor Create

POST /api/management/v2/datasets/<dataset_uid>/fields_specifications/

Requires one of the following:

Dataset System Processor Lookup

GET /api/management/v2/datasets/<dataset_uid>/fields_specifications/<processor_uid>/

Requires one of the following:

Dataset System Processor Update

PUT /api/management/v2/datasets/<dataset_uid>/fields_specifications/<processor_uid>/

Requires one of the following:

Dataset Processor Guess Params

POST /api/management/v2/datasets/<dataset_uid>/guess_processor_params/

Requires one of the following:

Dataset Metadata Index

GET /api/management/v2/datasets/<dataset_uid>/metadata/

Requires one of the following:

Dataset Metadata Lookup

GET /api/management/v2/datasets/<dataset_uid>/metadata/<template_name>/<metadata_name>/

Requires one of the following:

Dataset Metadata Update

PUT /api/management/v2/datasets/<dataset_uid>/metadata/<template_name>/<metadata_name>/

Requires one of the following:

Dataset Metadata Delete

DELETE /api/management/v2/datasets/<dataset_uid>/metadata/<template_name>/<metadata_name>/

Requires one of the following:

Dataset Processor Index

GET /api/management/v2/datasets/<dataset_uid>/processors/

Requires one of the following:

Dataset Processor Create

POST /api/management/v2/datasets/<dataset_uid>/processors/

Requires one of the following:

Dataset Processor Lookup

GET /api/management/v2/datasets/<dataset_uid>/processors/<processor_uid>/

Requires one of the following:

Dataset Processor Update

PUT /api/management/v2/datasets/<dataset_uid>/processors/<processor_uid>/

Requires one of the following:

Dataset Publish Action

PUT /api/management/v2/datasets/<dataset_uid>/publish/

Requires one of the following:

Dataset Unsaved Resource Preview

POST /api/management/v2/datasets/<dataset_uid>/resource_preview/

Requires one of the following:

Dataset Resource Index

GET /api/management/v2/datasets/<dataset_uid>/resources/

Requires one of the following:

Dataset Resource Create

POST /api/management/v2/datasets/<dataset_uid>/resources/

Requires one of the following:

Dataset Resource Lookup

GET /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/

Requires one of the following:

Dataset Resource Update

PUT /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/

Requires one of the following:

Dataset Resource Delete

DELETE /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/

Requires one of the following:

Dataset Resource Preview

GET /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/preview/

Requires one of the following:

Dataset Restore Change Action

PUT /api/management/v2/datasets/<dataset_uid>/restore_change/

Requires one of the following:

Dataset Schedule Index

GET /api/management/v2/datasets/<dataset_uid>/schedules/

Requires one of the following:

Dataset Schedule Create

POST /api/management/v2/datasets/<dataset_uid>/schedules/

Requires one of the following:

Dataset Schedule Lookup

GET /api/management/v2/datasets/<dataset_uid>/schedules/<schedule_uid>/

Requires one of the following:

Dataset Schedule Update

PUT /api/management/v2/datasets/<dataset_uid>/schedules/<schedule_uid>/

Requires one of the following:

Dataset Schedule Delete

DELETE /api/management/v2/datasets/<dataset_uid>/schedules/<schedule_uid>/

Requires one of the following:

Dataset Access Policy Lookup

GET /api/management/v2/datasets/<dataset_uid>/security/access_policy/

Requires one of the following:

Dataset Access Policy Update

PUT /api/management/v2/datasets/<dataset_uid>/security/access_policy/

Requires one of the following:

Dataset Default Security Lookup

GET /api/management/v2/datasets/<dataset_uid>/security/default/

Requires one of the following:

Dataset Default Security Update

PUT /api/management/v2/datasets/<dataset_uid>/security/default/

Requires one of the following:

Dataset Group Security Index

GET /api/management/v2/datasets/<dataset_uid>/security/groups/

Requires one of the following:

Dataset Group Security Create

POST /api/management/v2/datasets/<dataset_uid>/security/groups/

Requires one of the following:

Dataset Group Security Lookup

GET /api/management/v2/datasets/<dataset_uid>/security/groups/<group_id>/

Requires one of the following:

Dataset Group Security Update

PUT /api/management/v2/datasets/<dataset_uid>/security/groups/<group_id>/

Requires one of the following:

Dataset Group Security Delete

DELETE /api/management/v2/datasets/<dataset_uid>/security/groups/<group_id>/

Requires one of the following:

Dataset User Security Index

GET /api/management/v2/datasets/<dataset_uid>/security/users/

Requires one of the following:

Dataset User Security Create

POST /api/management/v2/datasets/<dataset_uid>/security/users/

Requires one of the following:

Dataset User Security Lookup

GET /api/management/v2/datasets/<dataset_uid>/security/users/<username>/

Requires one of the following:

Dataset User Security Update

PUT /api/management/v2/datasets/<dataset_uid>/security/users/<username>/

Requires one of the following:

Dataset User Security Delete

DELETE /api/management/v2/datasets/<dataset_uid>/security/users/<username>/

Requires one of the following:

Dataset Status

GET /api/management/v2/datasets/<dataset_uid>/status/

Requires one of the following:

Dataset Unpublish Action

PUT /api/management/v2/datasets/<dataset_uid>/unpublish/

Requires one of the following:

Catalog Export

GET /api/management/v2/export_datasets/<export_format>/

Requires one of the following:

Extractors Index

GET /api/management/v2/extractors/

Requires one of the following:

System Processor Index

GET /api/management/v2/fields_specifications/

Requires one of the following:

Guess Extractor Params

POST /api/management/v2/guess_extractor_params/

Requires one of the following:

Guess Extractors

POST /api/management/v2/guess_extractors/

Requires one of the following:

Processor Index

GET /api/management/v2/processors/

Requires one of the following:

Quotas and limits

Users and API keys can be limited in their usage in two ways:

The quotas object

Example object

"quotas": {
    "limit": 1000,
    "unit": "day"
}
Attribute Description
limit
number
The number of requests that can be performed by the user in the specified time period
unit
string
The time period of the limit (only day is supported)

The limits object

Example object

"limits": {
    "max_datasets": 500,
    "max_records_by_dataset": 1000000
}
Attribute Description
max_datasets
number
The maximum number of datasets that can be created by the user
max_records_by_dataset
number
The maximum number of records that can be published by the user

Files

On the Opendatasoft platform, files can be used as data source to create new datasets, and as dataset attachments, to add extra informations to datasets.

The file object

Example file object

{
    "file_id": "cheese_data.csv",
    "url": "odsfile://cheese_data.csv",
    "filename": "Cheese Data.csv",
    "properties": {
        "mimetype": "text/csv"
    },
    "created": "2017-06-07T15:16:05.701266+00:00"
}

The file object contains:

Attributes

Attribute Description
file_id
string
Unique identifier for the file
url
string
Generated internal URL, using the odsfile scheme
filename
string
 Human readable name of the file
properties
object
 Set of file properties, such as its mimetype
created
string
Time at which the file was created

List all files

This endpoint lists all files available to the user who performs the request. A file is available to the requesting user if either the user uploaded the file themselves, or if the user has sufficient permissions to edit a dataset where the file is used, or if the user is a domain administrator who has sufficient permissions to edit all datasets of the domain.

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/files

Example response

[
    {...},
    {
        "file_id": "cheese_data.csv",
        "url": "odsfile://cheese_data.csv",
        "filename": "Cheese Data.csv",
        "properties": {
            "mimetype": "text/csv"
        },
        "created": "2017-06-07T15:16:05.701266+00:00"
    },
    {...}
]

Retrieve information about one file

This endpoint is for retrieving the file object with provided file_id.

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/files/{FILE_ID}

Example request

curl 'https://yourdomain.opendatasoft.com/api/management/v2/files/cheese_data.csv'

Example response

{
    "file_id": "cheese_data.csv",
    "url": "odsfile://cheese_data.csv",
    "filename": "Cheese Data.csv",
    "properties": {
        "mimetype": "text/csv"
    },
    "created": "2017-06-07T15:16:05.701266+00:00"
}

Upload a file

This endpoint is for uploading a new file to the platform. There are two ways to send files to the platform: either by sending a full file using the HTTP multipart mechanism, or by sending the file content and other metadata such as its type and file name. The use case dictates which method works best. For instance, in order to create files out of batch processes it might be easier to use the content method, but to upload an existing file from a local hard drive, the multipart method might work better. Both methods have the same result: they create a file on the domain. Please note that no file over the limit of 240Mb can be uploaded.

 Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/files

This endpoint can receive a file sent in multipart, or file content sent through the content POST parameter, along with a mimetype and an optional filename.

Multipart file upload

The multipart file upload is an easy way to send a file with a HTML form. To do so, an example upload form is shown. Note that the name of the parameter is file.

Example HTML file upload form

<form action="https://yourdomain.opendatasoft.com/api/management/v2/files" method="post" enctype="multipart/form-data">
    <input type="file" name="file">
    <input type="submit">
</form>

Example multipart request

curl -XPOST 'https://yourdomain.opendatasoft.com/api/management/v2/files' \
    -F file=@data.csv
Parameter Description
file
POST parameter
file
Multipart file to upload. This is a POST parameter

POST content upload

Example POST content request

curl -XPOST 'https://yourdomain.opendatasoft.com/api/management/v2/files' \
    -H 'Content-Type: application/json' \
    -d '{"content": "language,phrase\nEnglish,Hello World\nEsperanto,Saluton mondo\n", "mimetype": "text/csv", "filename": "data.csv"}'
Parameter Description
content
string
Content of the file to create
mimetype
string
Mimetype of the file
filename
string
optional Name of the file. Defaults to file

Response

Example response

{
    "file_id": "data.csv",
    "url": "odsfile://data.csv",
    "filename": "data.csv",
    "properties": {
        "mimetype": "text/csv"
    },
    "created": "2017-06-07T15:16:05.701266+00:00"
}

On success, an HTTP 200 is returned along with the file object of the uploaded file.

Download a file

This endpoint is for downloading a file with the provided file_id from the platform.

 Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/download_file/{FILE_ID}

Parameters

Example request

curl 'https://yourdomain.opendatasoft.com/api/management/v2/download_file/data.csv'
Parameter Description
file_id
file
The file to download

Response

Example response

HTTP/1.1 200 OK
[...]
Content-Disposition: attachment; filename="data.csv"
Content-Type: text/csv; charset=utf-8


brand,color
Renault,blue
Citroën,red
Peugeot,white

On success, an HTTP 200 is returned with the file as an attachment.

Datasets

Datasets are at the core of the platform. A dataset is composed of:

Through the management API, it is possible to:

The dataset object

Example object

{
    "dataset_id": "my-dataset",
    "dataset_uid": "da_xlnu9n",
    "metas": {
        "default": {
            "modified": "2017-08-27T20:17:30+00:00",
            "language": "en",
            "title": "My Dataset"
        },
        "publishing": {
            "published": false
        }
    },
    "last_modified": "2017-09-12T09:55:43.952561+00:00",
    "status": {
        "name": "idle"
    }
}

Datasets are identified by 2 kinds of identifiers:

Attributes

Attribute Description
dataset_id
string
Human readable identifier of the dataset that can be modified when the dataset is not published
dataset_uid
string
Unique identifier of the dataset that will never change through the lifetime of the dataset
status
dataset status object
Current status of the object
changes
Array of dataset change objects
List of all changes made to the current object
metas
metadata object
Dictionary of attributes about the dataset like a title, a description, keywords, that make it easily searchable through the portal's catalog
last_modified
datetime
Date when the dataset's configuration was last edited
visibility
string
Defines if the dataset is visible for anonymous visitors
Can be domain if visibility is the same as the domain's visibility, or restricted if access is restricted to allowed users and groups
status
dataset status object
Keyword indicating if the dataset is waiting to be published, currently being published or if it encountered errors during last publishing

List datasets

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets \
    -u username:password

Example response

[
    {
        "dataset_id": "my-dataset",
        "dataset_uid": "da_xlnu9n",
        "metas": {
            "default": {
                "modified": "2017-08-27T20:17:30+00:00",
                "language": "en",
                "title": "My Dataset"
            },
            "publishing": {
                "published": false
            }
        },
        "last_modified": "2017-09-12T09:55:43.952561+00:00",
        "status": {
            "name": "idle"
        }
    },
    {...},
    {...}
]

This endpoint lists all the datasets that can be edited by this user.

Parameters

Parameter Default Description
where
string
None Filter expression used to restrict returned datasets (ODSQL documentation)
start
string
0 Index of the first item to return
rows
string
10 Number of items to return. Max value: 100
sort
string
None Field on which to sort the results list
include_app_metas
string
false Explicitely request application metadata for each datasets
timezone
string
UTC Timezone applied on datetime fields in query and response

Returns

Returns a list of dataset objects.

Create a dataset

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/

Example request for an empty dataset

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/ \
    -X POST \
    -u username:password
    -d '{}'

Example response for an empty dataset

{
    "dataset_id": "da_eb353e",
    "dataset_uid": "da_eb353e",
    "metas": {
        "default": {
            "modified": "2018-01-25T13:12:17+00:00"
        }
    },
    "last_modified": "2018-01-25T13:12:17+00:00",
    "status": {
        "name": "idle"
    }
}

Example request providing a title

curl http://yourdomain.opendatasoft.com/api/management/v2/datasets/ \
    -X POST \
    -u username:password
    -d '{"metas": {"default": {"title": "My dataset title"}}}'

Example response with the provided title

{
    "dataset_id": "my-dataset-title",
    "dataset_uid": "da_7qtcc3",
    "metas": {
        "default": {
            "modified": "2018-01-25T14:52:30+00:00",
            "title": "My dataset title"
        }
    },
    "last_modified": "2018-01-25T14:52:30+00:00",
    "status": {
        "name": "idle"
    }
}

Example request in strict mode

curl http://yourdomain.opendatasoft.com/api/management/v2/datasets/?strict=true \
    -X POST \
    -u username:password
    -d '{}'

Example response in strict mode

{
    "status_code": 400,
    "message": "Dataset identifier (dataset_id) is mandatory",
    "raw_params": {},
    "raw_message": "Dataset identifier (dataset_id) is mandatory",
    "error_key": "ODSException"
}

Creates a new dataset.

Parameters

Parameter Description
strict
boolean
Optional Flag preventing the application from generating a dataset_id if missing or altering it if already taken. Defaults to false.

Body

Parameter Description
dataset_id
string
optional unless in strict mode Human readable identifier that will be used to retrieve the dataset in the explore API.
If not specified, will be auto-generated (from the title metadata if available).
metas
object
optional Object providing a title to the new dataset.

Dataset status

The dataset status object

The dataset status describes the current state of a dataset, stating if it's published or not and the running operation. It is a finite state machine, with the following properties:

Here is the full state machine description.

Dataset states machine

Commons attributes

Attribute Description
published
boolean
true if the dataset is available in the search API
name
string
One of the dataset status values
since
datetime
Timestamp when the dataset entered in the current status
user
user
User who started the action

Retrieve the current dataset status

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/status

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/status \
    -u username:password

Example response

{
    "published": false,
    "status": "processing",
    "since": "2015-04-15T15:13:04+00:00"
}

Retrieves the current dataset status.

Parameters

No parameters

Returns

The dataset status object that applies to the given dataset. See Dataset status for specific attributes and the list of objects.

The idle dataset status

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/status?expand=records_errors \
    -u username:password

Example object

{
    "published": true,
    "status": "idle",
    "since": "2015-04-15T15:13:04+00:00",
    "records_errors": [
        {
            "record_id" : "442cdf84ec84de2474dfba9422b045c064c36f05",
            "processor_uid": "pr_XXXXXX",
            "field_uid": "column_1",
            "message": "Cannot convert \"a\" to \"int\"",
            "raw_message": "Cannot convert \"{value}\" to \"{type}\"",
            "raw_params": {
                "value": "a",
                "type": "int"
            }
        }
    ]
}
curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/status \
    -u username:password

Example object

{
    "published": true,
    "name": "idle",
    "since": "2015-04-15T15:13:04+00:00",
    "records_errors": 45
}

The idle status means that the dataset is not currently involved in an action. It can be published or not but no job is running. A newly created dataset is in that status.

Attributes

Attribute Description
records_errors
records errors object
Errors which occurred during the processing. Can be from a processor, or a type conversion. This attribute is present only if the dataset is published.

Transitions leading to the status

Transition origin status Transition condition
processing Processing ended successfully
deleting Deleting ended successfully
aborting_processing Processing aborted

Transitions leaving the status

Transition destination status Transition condition
queued The order has been received and is waiting to be realised

The error dataset status

Example object

{
    "published": true,
    "name": "error",
    "since": "2015-04-15T15:13:04+00:00",
    "message": "Processor pr_XXXXXX is misconfigured for field address: invalid type",
    "raw_message": "Processor {processor_id} is misconfigured for field {field}: {msg}",
    "raw_params": {
        "processor_id": "pr_XXXXXX",
        "field": "address",
        "msg": "invalid type"
    }

}

The error status means that the action failed. It can be an error from the source or a pipeline misconfiguration.

Attributes

Attribute Description
raw_message Template for the error message, parameters are not replaced
raw_params Parameters values, to be injected in the raw_message
message English message with the replaced parameter

Transitions leading to the status

Status Condition
processing Processing ended with an error
deleting Deleting ended with an error

Transitions leaving the status

Status Condition
queued The order has been received and is waiting to be realised

The limit_reached dataset status

Example object

{
    "published": true,
    "name": "limit_reached",
    "since": "2015-04-15T15:13:04+00:00"
}

The limit_reached status means that the dataset stopped processing records because it reached the maximum of authorized records in the license.

Attributes

No specific attribute

Transitions leading to the status

Status Condition
processing Processing stopped because of too many records in the dataset

Transitions leaving the status

Status Condition
queued The order has been received and is waiting to be realised

The queued dataset status

Example object

{
    "published": true,
    "name": "queued",
    "since": "2015-04-15T15:13:04+00:00"
}

The queued status means that the action has been received and is waiting to be performed.

Attributes

No specific attribute

The processing dataset status

Example object

{
    "published": true,
    "name": "processsing",
    "since": "2015-04-15T15:13:04+00:00"
}

The processing status means that dataset's metadata or data (with the extraction, transformation ...) are being made available to the search API.

Transitions leading to the status

Status Condition
queued A worker is available

Transitions leaving the status

Status Condition
idle The processing ended successfully
error The processing ended with an error
limit_reached The processing stopped because it reached the maximum number of records allowed in the license
aborting_processing The processing is aborting

The deleting dataset status

Example object

{
    "published": true,
    "name": "deleting",
    "since": "2015-04-15T15:13:04+00:00"
}

The deleting status means that the dataset's metadata and data are being removed from the search API.

Attributes

No specific attribute

Transitions leading to the status

Status Condition
queued A worker is available

Transitions leaving the status

Status Condition
processing Records are currently processing
idle The processing ended successfully
error The processing ended with an error
limit_reached The processing stopped because it reached the maximum number of records allowed in the license

The aborting_processing dataset status

Example object

{
    "published": true,
    "name": "aborting_processing",
    "since": "2015-04-15T15:13:04+00:00"
}

The aborting_processing status means that the order to stop the processing has been received and the processing will stop shortly

Attributes

No specific attribute

Transitions leading to the status

Status Condition
processing The abort order is received

Transitions leaving the status

Status Condition
idle The processing ended successfully
error The processing ended with an error

Dataset actions

The state of a dataset can be changed by triggering actions. An action can make the dataset available through the search API or remove it from the search API. Available actions are:

Publish a dataset

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/publish

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/publish \
    -X PUT \
    -u username:password

Example response

{
    "job_id": "e0f8a9cf495a0ee617b0828da35f349bbb62ad43"
}

Make the dataset modifications available through the search API. It may entail the processing of all the records.

Parameters

No parameters

Returns

Returns a job object.

Unpublish a dataset

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/unpublish

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/unpublish \
    -X PUT \
    -u username:password

Example response

{
    "job_id": "e0f8a9cf495a0ee617b0828da35f349bbb62ad43"
}

Remove the dataset from the search API. Unpublishing a dataset does not delete the dataset.

Parameters

No parameters

Returns

Returns a job object.

Abort a dataset processing

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/abort_processing

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/abort_processing \
    -X PUT \
    -u username:password

Example response

HTTP/2 200

Stop the current processing job and keep the processed records available in the search API.

Parameters

No parameters

Returns

Returns a job object.

Delete a dataset

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX \
    -X DELETE \
    -u username:password

Delete the dataset.

Parameters

No parameters

Returns

Returns nothing

Record error

The record error object

The record error describes errors which occurred during the processing. An error comes from:

Attributes

Attribute Description
record_id
string
Identifier of the record after processing
processor_uid
string
Unique identifier of the processor which generates the error
field_uid
string
Unique identifier of the field involved in the error
raw_message
string
Message with parameters template
raw_params
params object
Json object with parameters templates values
message
string
Message with replaced parameters

Retrieve the records errors

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/status/records_errors

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/records_errors \
    -u username:password

Example response

{
    "record_id" : "442cdf84ec84de2474dfba9422b045c064c36f05",
    "processor_uid": "pr_XXXXXX",
    "field_uid": "column_1",
    "message": "Cannot convert \"a\" to \"int\"",
    "raw_message": "Cannot convert \"{value}\" to \"{type}\"",
    "raw_params": {
        "value": "a",
        "type": "int"
    }
}

Retrieves the dataset records errors generated by the last publish.

Parameters

No parameters

Returns

The list of record error objects that apply to the given dataset. See record error object for specific attributes and the list of objects.

Params object

Example value

{
    "param_1" : "value_1",
    "param_2" : "value_2",
    "param_3" : "value_3"
}

A key/value json object.

Dataset changes

The changes of a dataset describe subsequent changes of states that affected the different sections of a dataset. Every action taken on any resource through POST, PUT or DELETE creates a change object that can be retrieved and acted upon.

The change object

Example object

{
    "change_uid": 125,
    "dataset": {
        "dataset_uid": "dataset",
        "domain": "domain"
    },
    "user": {
        "username": "john_smith"
    },
    "timestamp": "2017-06-07T15:16:05.701266+00:00",
    "diff": {
        "metadata": [{
            "path": ["default", "description"],
            "old_value": null,
            "new_value": "dataset title",
            "operation_type": "create"
        }]
    },
    "sections": [
        "metadata"
    ]
}

The change object contains:

Attributes

Attribute Description
change_uid
string
Unique identifier for the change
dataset
dataset object
Dataset targeted by the change
expandable
user
user object
User who made the change
expandable
timestamp
string
Time at which the change was made
diff
string
Difference between the state before and after the change
sections
array
Sections modified by this change

List all changes

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/changes

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/changed_dataset/changes \
    -u username:password

Example response

[
    {
        "change_uid": 126,
        "dataset": {
            "dataset_uid": "changed_dataset",
            "domain": "domain"
        },
        "user": {
            "username": "john_smith"
        },
        "timestamp": "2017-06-07T15:16:05.701266+00:00",
        "diff": {
            "security": [{
                "path": ["user", "jane_doe"],
                "old_value": null,
                "new_value": {
                    "data_visible": true
                },
                "operation_type": "create"
            }]
        },
        "sections": [
            "security"
        ]
    },
    {...},
    {...}
]

This endpoint lists all changes made to a dataset.

Parameters

Parameter Description
dataset_uid
string
Identifier of the dataset whose changes are to be listed

Returns

Returns a list of changes for this datasets.

Restore a change

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/restore_change

Example request

curl -XPUT https://yourdomain.opendatasoft.com/api/management/v2/restore_change \
    -u username:password -d '{ "change_uid": 126 }'

Example response

HTTP/2 200

Restores a dataset to the state it was before the selected change happened. Restoring a change will not erase the change history, but rather create a new change encapsulating the restoration.

Parameters

Parameter Description
dataset_uid
string
Identifier of the dataset to restore to a previous change
change_uid
string
Identifier of the change to restore. This parameter must be sent in the json format, inside a json object

Returns

On success, a HTTP 200 is returned.

Dataset resources

The resource object

The resource object describes a resource on the Opendatasoft platform. It is composed of a URL, a title, a type, a parameter object and a credentials object. The URL is where data will be pulled to populate the dataset. Resources urls can (and often do!) point to files uploaded to the platform using the odsfile:// url scheme.

Attributes

Example object

{
    "resource_uid": "re_abcdef",
    "url": "odsfile://resource.csv",
    "title": "My Awesome Data File",
    "type": "csvfile",
    "params": {
        "headers_first_row": false,
        "separator": ";"
    },
    "credentials": {},
}
Attribute Description
resource_uid
string
Unique identifier for the resource
url
string
URL of the resource
title
string
friendly title
type
extractor
extractor type that should handle this resource
params
object
parameters passed to the extractor
credentials
object
resource credentials

List dataset resources

This endpoint is meant to list all resources that are linked to a dataset.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resources/

Example request

curl -XGET https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/resources/
    -u username:password

Example response

[{
    "resource_uid": "re_abcdef",
    "url": "odsfile://resource.csv",
    "title": "My Awesome Data File",
    "type": "csvfile",
    "params": {
        "headers_first_row": false,
        "separator": ";"
    },
    "credentials": {}
}, {...}]

Returns

This API call returns the list of resource objects linked to the dataset.

Create a new resource

This endpoint is for creating a new resource for the dataset

Definition

POST https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resources/

Example request

curl -XPOST https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/resources/
    -u username:password \
    -d '{ "url": "odsfile://resource.csv", "title": "My Awesome Data File", "type": "csvfile", "params": {"headers_first_row": false, "separator": ";"}, "credentials": {} }'

Example response

{
    "resource_uid": "re_abcdef",
    "url": "odsfile://resource.csv",
    "title": "My Awesome Data File",
    "type": "csvfile",
    "params": {
        "headers_first_row": false,
        "separator": ";"
    },
    "credentials": {}
}

A new resource is created using the resource object sent in the body, and echoes back the object, with its newly generated resource_uid on success.

Parameters

The payload must be a valid resource object without any uid.

Returns

The newly created resource object with its newly created resource uid.

Retrieve a resource object

This endpoint is for retrieving one resource object using its resource uid

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resources/{RESOURCE_UID}

Example request

curl -XGET https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/resources/{RESOURCE_UID}
    -u username:password

Example response

{
    "resource_uid": "re_abcdef",
    "url": "odsfile://resource.csv",
    "title": "My Awesome Data File",
    "type": "csvfile",
    "params": {
        "headers_first_row": false,
        "separator": ";"
    },
    "credentials": {}
}

This API endpoint takes in its URL path a resource uid and returns the associated object.

Returns

The resource object with the given resource uid.

Delete a resource

This endpoint is meant to delete a resource specified by its uid.

Definition

DELETE https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resources/{RESOURCE_UID}

Example request

curl -XDELETE https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/{RESOURCE_UID}
    -u username:password

This API endpoint takes a resource UID in its URL path and deletes the resource associated to it. On success it returns a bare 204 HTTP response.

Update a resource

This API endpoint is meant to update a resource specified with its uid.

Definition

PUT https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resources/{RESOURCE_UID}

Example request

curl -XPUT https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/resources/{RESOURCE_UID}
    -u username:password \
    -d '{ "url": "odsfile://resource.csv", "title": "My Awesome Data File", "type": "csvfile", "params": {"headers_first_row": false, "separator": ";"}, "credentials": {} }'

Example response

{
    "resource_uid": "re_abcdef",
    "url": "odsfile://resource.csv",
    "title": "My Awesome Data File",
    "type": "csvfile",
    "params": {
        "headers_first_row": false,
        "separator": ";"
    },
    "credentials": {}
}

This endpoint takes a resource uid in its url path and a resource object in its payload and updates the associated resource with the content of the payload.

Parameters

The payload must be a valid resource object without any uid.

Returns

The newly updated resource object.

Preview the first few rows of the extracted resource

In order to test a resource configuration, it can be useful to preview the data. There are two ways of doing this, one uses the configuration of an existing resource to generate a preview, and the other one uses the configuration passed in the payload.

Payload-based call definition

POST https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resource_preview

UID-based call definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/resources/{RESOURCE_UID}/preview

Example payload-based request

curl -XPOST https://yourdomain.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resource_preview
    -u username:password \
    -d '{ "url": "odsfile://resource.csv", "title": "My Awesome Data File", "type": "csvfile", "params": {"headers_first_row": false, "separator": ";"}, "credentials": {} }'

Example UID-based request

curl -XGET https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/resources/re_abcdef/preview
    -u username:password

Example response

{
    "fields": [{
        "description": null,
        "original_name": "column_1",
        "label": "Column 1",
        "type": "text",
        "annotations": [],
        "name": "column_1"
    }],
    "records": [
        {"column_1": "Hello"},
        {"column_1": "World"}
    ]
}

The payload-based call is sent in POST with a resource object in its body from which the endpoint takes its configuration to generate its preview. The resource_uid-based call uses an actual resource of the dataset by uid to generate a preview. The preview is composed of the fields definitions and the content of the first records up to 20.

Parameters

For the payload-based call, the payload must be a valid resource object without any uid.

Returns

The fields definitions and first few records extracted from the resource.

Dataset metadata

Metadata is data describing the dataset itself. This is a set of fields describing the data, such as a title, a description, a list of keywords, a modification date, or whether the dataset is compliant to a specific geospatial norm. Adding metadata on a dataset is important to make sure it can be found, understood, and reused by users. In some cases, it can also be important for interoperability, to make sure other systems can understand the content of the dataset.

Dataset metadata are grouped within metadata templates that you can think of as namespaces. On top of the default metadata template, you may also find (depending on your domain's configuration) the inspire, dcat or citadeljson templates. Many other templates also exist and you can contact the support to define your own templates.

The metadata object

This object stores both the definition and the value of a given metadata.

Attributes

Example object

{
    "name": "title",
    "template": {
        "name": "default",
        "label": "Default metadata",
        "purpose": "general"
    },
    "definition": {},
    "value": "My agenda",
    "remote_value": "agendav2",
    "override_remote_value": true
}
Attribute Description
name
string
Identifier for the object (inherited from the definition's name)
template
metadate template object
Group of the current object
definition
form object
The definition of the metadata type and widget
value The object's value (may not be the indexed value, see below)
remote_value The remote object's metadata value (see below)
override_remote_value
boolean
Flag indicating whether the indexed value is value or remote_value

In the case of federated and harvested datasets, metadata values are automatically collected from the remote source, showing up in the object as remote_value. You can however override this value with your own, specifying it in value and setting the override_remote_value flag to True. This flag determines which value will show up in the explore API output.

The metadata template object

Example object

{
    "name": "default",
    "label": "Default metadata",
    "purpose": "general"
}

This object describes a category of metadata, a group. It has a purpose property with the following meaning.

Purposes

Type  Description
general Standard metadata values, their purpose is to describe the dataset to the end user.
interop Sets of metadata values following an explicit norm for interoperability purposes.
Examples of such norms: DCAT, INSPIRE.
admin Metadata values only meant for data publisher. These values will never show up in the explore APIs and are only visible in this management API by people having the permission to edit the dataset.

Attributes

Attribute Description
name
string
 Identifier for the object
label
string
Plain text label of the object
purpose
string
Purpose of the object.
Possible values are general, interop and admin

List all metadata

Returns a list of metadata for the dataset with the given UID.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_ID}/metadata

Parameters

No parameters.

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/metadata \
    -u username:password

Returns

The full list of metadata objects.

Example response

[
    {
        "name": "title",
        "template": {
            "name": "default",
            "label": "Default metadata",
            "purpose": "general"
        },
        "definition": {},
        "value": "My agenda",
        "remote_value": "agendav2",
        "override_remote_value": true
    },
    {...},
    {...}
]

Retrieve a metadata

Retrieves the metadata with the given name within the given template.

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/metadata/{TEMPLATE_NAME}/{METADATA_NAME}

Parameters

No parameters.

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/metadata/default/title \
    -u username:password

Returns

A metadata object.

Example response

{
    "name": "title",
    "template": {
        "name": "default",
        "label": "Default metadata",
        "purpose": "general"
    },
    "definition": {},
    "value": "My agenda",
    "remote_value": "agendav2",
    "override_remote_value": true
}

Update a metadata value

Definition

PUT https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/metadata/{TEMPLATE_NAME}/{METADATA_NAME}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/metadata/default/title \
    -u username:password \
    -X PUT \
    -d '{"value": "The best agenda", "override_remote_value": true}'

Example response

{
    "name": "title",
    "template": {
        "name": "default",
        "label": "Default metadata",
        "purpose": "general"
    },
    "definition": {},
    "value": "The best agenda",
    "remote_value": "agendav2",
    "override_remote_value": true
}

Updates the value of a metadata.

Parameters

A json object passed in the request's body.

General case

Parameter Description
value The new metadata value.
Must conform to the metadata definition's type. Can be null.

For federated and harvested datasets

Parameter Description
value The new metadata value.
Must conform to the metadata definition's type. Can be null.
override_remote_value
boolean
Flag indicating whether the indexed value is value or remote_value. If false the value of value is always deleted.

Returns

The updated metadata object.

Reset a metadata value

Definition

DELETE https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/{TEMPLATE_NAME}/{METADATA_NAME}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/metadata/default/title \
    -u username:password \
    -X DELETE

Example response

{
    "name": "title",
    "template": {
        "name": "default",
        "label": "Default metadata",
        "purpose": "general"
    },
    "definition": {},
    "value": null,
    "remote_value": "agendav2",
    "override_remote_value": false
}

Resets a metadata value by deleting the value property.

For federated and harvested datasets, it also sets the override_remote_value flag to false.

As a result, the metadata value won't show up in the explore API output anymore. Unless it is a federated or harvested dataset with a remote_value set.

Parameters

No parameters.

Returns

The reset metadata object.

Dataset attachments

Dataset attachments are files that are exposed along with a dataset. These files help make sense of the data.

The attachment object

The attachment object contains information about the file.

Attributes

Example object

{
    "attachment_uid": "at_cba987",
    "url": "odsfile://file.csv"
}
Attribute Description
attachment_uid
string
A string that defines an attachment
url
URL of file
URL of the backing file

List attachments

This endpoint is for listing all attachments to a dataset.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/attachments

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/attachments
    -u username:password

Example response

[{
    "attachment_uid": "at_cba987",
    "url": "odsfile://file.csv"
},{
    "attachment_uid": "at_abc123",
    "url": "odsfile://file2.csv"
}]

Parameters

No parameters

Returns

A list of attachment objects.

Create an attachment

This endpoint is for attaching a file to a dataset.

Definition

POST https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/attachments

Example request

curl -XPOST https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/attachments
    -u username:password \
    -d {"url": "odsfile://file.csv"}

Parameters

Parameter Description

url
The URL of the file to attach to the dataset. This can be a odsfile.

Returns

The attachment objects for the newly created attachment.

Retrieve information about one attachment

This endpoint is for retrieving information about an attachment with its UID.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/attachments/{ATTACHMENT_UID}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/attachments/at_XXXXXX
    -u username:password

Example response

{
    "attachment_uid": "at_cba987",
    "url": "odsfile://file.csv"
}

Parameters

Parameter Description
attachment_uid Identifier of the attachment to retrieve

Returns

The attachment objects corresponding to the attachment ID.

Delete an attachment

This endpoint is for deleting a dataset attachment.

Definition

DELETE https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/attachments/{ATTACHMENT_UID}

Example request

curl -XDELETE https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/attachments/at_XXXXXX
    -u username:password

Parameters

No parameters

Returns

On success, an HTTP 200 is returned

Download an attachment

This endpoint is for downloading a file attached to a dataset.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/download_attachment/{ATTACHMENT_UID}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/download_attachment/at_XXXXXX
    -u username:password

Parameters

No parameters

Returns

The attached file

Dataset alternative exports

Dataset alternative exports are custom dataset exports made outside of the platform but available for end users to download like a normal export in the export menu. Alternative exports are userful to expose exports in formats not supported by the platform, or in a specific geographic coordinate system. Since alternative exports are static files instead of dynamic exports, they tend to be very fast to download for end users and can be useful to offer a very large dataset export.

The alternative export object

The alternative export object contains information about the file.

Attributes

Example object

{
    "export_uid": "ae_bab015",
    "url": "odsfile://file.csv"
}
Attribute Description
export_uid
string
A string that defines an alternative export
url
URL of file
URL of the backing file

List alternative exports

This endpoint is for listing all alternative exports of a dataset.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/alternative_exports

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/alternative_exports
    -u username:password

Example response

[{
    "export_uid": "ae_bab015",
    "url": "odsfile://file.csv"
},{
    "export_uid": "ae_6539f8",
    "url": "odsfile://file2.csv"
}]

Parameters

No parameters

Returns

A list of alternative export objects.

Create an alternative export

This endpoint is for attaching a file to a dataset.

Definition

POST https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/alternative_exports

Example request

curl -XPOST https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/alternative_exports
    -u username:password \
    -d {"url": "odsfile://sorted_export.csv"}

Parameters

Parameter Description

url
The URL of the export. This can be a odsfile.

Returns

The alternative export objects for the newly created alternative export.

Retrieve information about one alternative export

This endpoint is for retrieving information about an alternative export with its UID.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/alternative_exports/{EXPORT_UID}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/alternative_exports/ae_XXXXXX
    -u username:password

Example response

{
    "export_uid": "ae_bab015",
    "url": "odsfile://sorted_export.csv"
}

Parameters

Parameter Description
export_uid Identifier of the alternative export to retrieve

Returns

The alternative export objects corresponding to the alternative export ID.

Delete an alternative export

This endpoint is for deleting a dataset alternative export.

Definition

DELETE https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/alternative_exports/{EXPORT_UID}

Example request

curl -XDELETE https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/alternative_exports/ae_XXXXXX
    -u username:password

Parameters

No parameters

Returns

On success, an HTTP 200 is returned

Download an alternative export

This endpoint is for downloading a file attached to a dataset.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/download_alternative_export/{EXPORT_UID}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/download_alternative_export/ae_XXXXXX
    -u username:password

Parameters

No parameters

Returns

The attached file

Dataset security

The dataset security is the set of rules that defines who (which users / groups) can access what (which metadata / records / fields) at what frequency (api calls quota) for a given this dataset.

It is defined through 3 variables:

Restricted datasets

If the dataset is set as restricted, then the dataset will only appear in the catalog for users who have a ruleset declared for them, either directly or through a group. Other users won't have any access to the dataset.

The default security ruleset has no meaning for restricted datasets.

Standard access datasets

Anyone having access to the domain will be able to see the dataset in the catalog.

Users who have at least a ruleset declared for them (whether directly, through a group or both) will be able to see everything their rulesets grant access to.

Users who do not have any ruleset declared for them (neither directly nor through a group), they will be able to see what the default ruleset grants access to.

The dataset security API in a nutshell

General access policy

/dataset/{DATASET_UID}/security/access_policy

Default security ruleset

/dataset/{DATASET_UID}/security/default

User level security ruleset

/dataset/{DATASET_UID}/security/users

/dataset/{DATASET_UID}/security/users/{USERNAME}

Group level security ruleset

/dataset/{DATASET_UID}/security/groups

/dataset/{DATASET_UID}/security/groups/{group_id}

The general access policy

A flag indicating whether the dataset is accessible by all people having access to the domain or just a few with explicit authorization.

There are two acceptable values for the flag:

Retrieve the general access policy

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/security/access_policy

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/security/access_policy \
    -u username:password

Example response

"domain"

Retrieves the general access policy set for the dataset.

Set the general access policy

Definition

PUT https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/security/access_policy

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/security/access_policy \
    -u username:password \
    -X PUT \
    -d '"restricted"'

Example response

"restricted"

Sets the general access policy for the dataset.

Payload

A single string.
Possible values are domain and restricted.

The ruleset object

A set of rules defining what the target can see.

The target can be:

Example object

{
    "is_data_visible": true,
    "visible_fields": ["field1", "field2"],
    "filter_query": "",
    "api_calls_quota": {
        "limit": 10000,
        "unit": "day"
    },
    "permissions": [],
    "user": {
        "username": "username"
    }
}

Attributes

Attribute  Description
visible_fields
array of field names (string)
The target will only have access to the fields from this list.
['*'] means that the target has access to all fields.
An empty list means that the target won't see any field (empty dataset schema).
is_data_visible
boolean
Flag indicating whether the target will have access to the records of the dataset or not.
filter_query
string
The target will only have access to the records matching this query. An empty query means that all records are accessible.
permissions
array of strings
List of special permissions granted to the target.
Only available for user and group-level rulesets.
Possible values are edit_dataset, publish_dataset, manage_dataset
api_calls_quota
quota object
Upper limit set on the number of api calls the target can make to this dataset in a given timeframe.
Can be set to null for no specific quota.
user
user object
The user targeted by this ruleset.
Only available for user-level rulesets.
group
group object
The group targeted by this ruleset.
Only available for group-level rulesets.

Retrieve the default security ruleset

Retrieves the default security ruleset, that is the ruleset that applies when no specific ruleset is declared for the user or one of their groups.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/security/default

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/security/default \
    -u username:password

Example response

{
    "is_data_visible": false,
    "visible_fields": ["field1", "field2"],
    "filter_query": "",
    "api_calls_quota": null,
    "permissions": []
}

Update the default security ruleset

PUT datasets/<dataset_uid>/security/default

Reset the default security ruleset

DELETE datasets/<dataset_uid>/security/default

Retrieve all user level security rulesets

Retrieves all rulesets defined for specific users. The rulesets are ordered by ascending username.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/security/users

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/security/users \
    -u username:password

Example response

[
    {
        "user": {
            "username": "username"
        },
        "is_data_visible": false,
        "visible_fields": ["field1", "field2"],
        "filter_query": "",
        "api_calls_quota": null,
        "permissions": []
    },
    {...},
    {...}
]

Create a new user level security ruleset

POST datasets/<dataset_uid>/security/users

Retrieve a user level security ruleset

Retrieves the ruleset defined for a specific user. Returns an error if no ruleset is defined for the user.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/security/users/{USERNAME}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/security/users/username \
    -u username:password

Example response

{
    "user": {
        "username": "username"
    },
    "is_data_visible": false,
    "visible_fields": ["field1", "field2"],
    "filter_query": "",
    "api_calls_quota": null,
    "permissions": []
}

Update a user level security ruleset

Updates the ruleset defined for the given user. Returns an error if no such ruleset is defined.

Definition

PUT https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/security/users/{USERNAME}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/security/users/username \
    -u username:password
    -X PUT \
    -d '{"user": {"username": "username"}, "is_data_visible": true, "visible_fields": [], "filter_query": "", "api_calls_quota": null, "permissions": []}'

Example response

{
    "user": {
        "username": "username"
    },
    "is_data_visible": true,
    "visible_fields": [],
    "filter_query": "",
    "api_calls_quota": null,
    "permissions": []
}

Delete a user level security ruleset

DELETE datasets/<dataset_uid>/security/users/<username>

Retrieve all group level security rulesets

GET datasets/<dataset_uid>/security/groups

Create a new group level security ruleset

POST datasets/<dataset_uid>/security/groups

Retrieve a group level security ruleset

GET datasets/<dataset_uid>/security/groups/<group_id>

Update a group level security ruleset

PUT datasets/<dataset_uid>/security/groups/<group_id>

Delete a group level security ruleset

DELETE datasets/<dataset_uid>/security/groups/<username>

Processing

The Opendatasoft platform allows you to apply one or more processors to a dataset. These processors are units of data transformation and other processing. Each processor represents a configurable operation that will be applied to all rows of a dataset. Examples of what you can do with a processor include replacing text with a regex, geocoding an address into geographical coordinates, creating a new column that contains the result of a substraction between two existing columns and much more. A general-purpose presentation of processors and their capabilities is available on the data processing documentation.

The processor object

The processor object is composed of a unique ID for the processor, the processor name and the processor configuration. The configuration is a JSON object whose keys are dependent of the processor itself.

Attributes

Example object

{
    "processor_uid": "pr_abcdef", 
    "name":"regexp_replace",
    "args": {
        "field": "text_field",
        "regexp": ".*",
        "new": "Hello World"
    }
}
Attribute Description
name
string
Name of the processor
args
object
Processor configuration
processor_uid
string
Unique identifier for the processor

List all available processors

This endpoint allows the caller to find out what processors are available to them

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/processors/

Example request

curl -XGET https://yourdomain.opendatasoft.com/api/management/v2/processors/
    -u username:password

Example response

[
    "regexp_replace",
    "transform_coordinates",
    "string_extractor",
    "skip_record",
    "create_geopoint",
    "split",
    "delete_record",
    "set_timezone",
    "string_replace",
    "date_normalizer",
    "geojoin",
    "concat",
    "geo_distance",
    "expression",
    "unicode_normalize",
    ...
]

The endpoint returns a list of all processors available on the domain.

Returns

The list of all available processor names.

List dataset processors

This endpoint is meant to return the list of configured processors for a dataset.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/processors/

Example request

curl -XGET https://yourdomain.opendatasoft.com/api/management/datasets/da_abcdef/processors/
    -u username:password

Example response

[{
    "processor_uid": "pr_abcdef", 
    "name":"regexp_replace",
    "args": {
        "field": "text_field",
        "regexp": ".*",
        "new": "Hello World"
    }
}, {
    "processor_uid": "pr_zyxwvu",
    "name": "string_replace",
    "args": {
        "field": "text_field",
        "all_fields": false,
        "old": "World",
        "new": "World!"
    }
}]

The payload lists the processing stack of the dataset. Please note that it reads in the order in which processors are applied.

Returns

The list of processor objects.

Append a new processor to a dataset

This endpoint is for creating a new processor for the dataset. The processor will be appended to the end of the processing stack.

Definition

POST https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/da_abcdef/processors/

Example request

curl -XPOST https://yourdomain.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/processors/
    -u username:password \
    -d '{"name": "string_extractor", "args": {"field": "text_field", "regexp": "(?P<planet>^World)"}'

Example response

{
    "processor_uid": "pr_newnew",
    "name": "string_extractor",
    "args": {
        "field": "text_field",
        "regexp": "(?P<planet>^World)"
    }
}

The endpoint takes a processor object (without its processor_uid, which will be automatically generated), creates a processor with the provided configuration and appends it at the end of the processing chain.

Parameters

Parameter Description
name
string
name of the processor
args
object
processor-dependent parameters

Returns

The newly created processor object.

Retrieve informations about a processor

This endpoint is meant to retrieve a processor object in a dataset processing stack from its uid.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/processors/{PROCESSOR_UID}

Example request

curl -XGET https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_abcdef/processors/pr_newnew
    -u username:password

Example response

{
    "processor_uid": "pr_newnew",
    "name": "string_extractor",
    "args": {
        "field": "text_field",
        "regexp": "(?P<planet>^World)"
    }
}

Returns

The requested processor object.

Update a processor

This endpoint is meant to update a processor in place within the processing stack of a dataset.

Definition

PUT https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/processors/{PROCESSOR_UID}

Example request

curl -XPUT https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_abcdef/processors/pr_abcdef
    -u username:password \
    -d '{"name":"regexp_replace", "args": {"field": "text_field", "regexp": ".*", "new": "Bonjour Monde"}'

Example response

{
    "processor_uid": "pr_abcdef", 
    "name":"regexp_replace",
    "args": {
        "field": "text_field",
        "regexp": ".*",
        "new": "Bonjour Monde"
    }
}

Parameters

Parameter Description
name
string
name of the processor
args
object
processor-dependent parameters

Returns

The newly updated processor object.

Delete a processor

This endpoint is meant to delete a processor from the processing stack of a dataset

Definition

DELETE https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/processors/{PROCESSOR_UID}

Example request

curl -XDELETE https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_abcdef/processors/pr_newnew
    -u username:password

Returns

On successful deletion, the endpoint returns a HTTP 204 without any content.

Retrieve possible processor parameters from processor name

For some processors and some processors parameters, the Opendatasoft platform has a way to suggest values for the processor parameters. It can for instance figure out the list of fields the processor could operate on.

This endpoint is meant to expose this feature, by taking a processor name and returning the set of possible values for each parameter.

Definition

POST https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/guess_processor_params

Example request

curl -XPOST https://yourdomain.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/guess_processor_params
    -u username:password \
    -d '{"name": "expand_json_array"}'
}

Example response

{
    "json_array_field": {
        "text_field": {
            "annotations": [],
            "description": null,
            "label": "text_field",
            "name": "text_field",
            "original_name": "text_field",
            "type": "text"
        }
    }
}

The endpoint takes the name of a processor and suggest relevant configuration values as if a processor of that type was appended to the processing stack. The parameters are returned in an object structure, that is as key values pair. The values in these pairs are any extra relevant information, such as the dataset field specification. Please note that some parameters cannot be guessed and will simply be returned empty.

Parameters

Parameter Description
name
string
name of the processor

Returns

The endpoint returns an object whose keys are the names of the processor parameters, and whose values are objects containing the guessed values. These values have their name as keys and specifications as value.

Fields specification

Dataset fields can be configured using a variety of options. These options include their type, their label, whether they are a filter or not, whether they should be discarded, or even how fields are ordered. These configuration options, collectively refered to as fields specification, are accessed using processor-like objects.

Available configuration items

Here is a comprehensive list of the available configuration items. Example usage for each one can be found in their dedicated section.

Configuration name Description
rename changes the name of the field and sets its label
type sets the field type
annotate annotates the field
description describes the field
order reorders fields
delete deletes a field

Rename

 change the field named "original_field_id" to "new_field_id", and set its label to "desired_label"

{
    "name": "rename",
    "args": {
        "from_name": "original_field_id",
        "to_name": "new_field_id",
        "label": "desired_label"
    }
}

Fields are identified by a technical name, and have a human-friendly label; both are editable using this configuration item.

Type

change the type of the field named "field_id" to a geo shape

{
    "name": "type",
    "args": {
        "field": "field_id",
        "type": "geo_shape"
    }
}

Types are the most basic way of qualifying fields. Different types unlock different kinds of visualizations and agregations. Below is the list of types supported by the platform.

Type name Description
text text
int  integer
double floating point
geo_point_2d geographical location (2 dimensions)
geo_shape geographical shape
date  date
datetime  date and time
file  file (blob)

Annotate

mark the unique_field as the unique ID for the records

{
    "name": "annotate",
    "args": {
        "field": "unique_field",
        "annotation": "id"
    }
}

mark the category_field as a facet

{
    "name": "annotate",
    "args": {
        "field": "category_field",
        "annotation": "facet"
    }
}

make the facetted_field facet be sorted by descending count

{
    "name": "annotate",
    "args": {
        "field": "facetted_field",
        "annotation": "facetsort",
        "args": ["-count"]
    },
}

make the datetime_field have an hourly precision when used in timeseries

{
    "name": "annotate",
    "args": {
        "field": "datetime_field",
        "annotation": "timeseries_precision",
        "args": ["hour"]
    },
}

mark the nondescript_number field as representing square kilometers

{
    "name": "annotate",
    "args": {
        "field": "nondescript_number",
        "annotation": "unit",
        "args":["km2"]
    },
}

force the decimal_field precision to 5 digits after the decimal point

{
    "name": "annotate",
    "args": {
        "field": "decimal_field",
        "annotation": "decimals",
        "args": [5]
    },
}

mark the multivalued_field as multivalued, with a comma as the values separator

{
    "name": "annotate",
    "args": {
        "field": "multivalued_field",
        "annotation": "multivalued",
        "args": [","]
    },
}

Annotation are a mean to configure special behavior for the fields. Some annotations are only available for certain field types. Setting the facet annotation on a field unlocks other annotations for the field.

Annotation name Field type Description
id all field types Whether this field should constitute one of the keys of the records unique IDs. If no field has this annotation, all fields contribute to the creation of the records unique ID.
facet date, datetime, int, decimal, text Whether the field can serve as a filter
facetsort all field types, facet only How to sort the facets. Possible arguments are count and -count for all field types, alphanum and -alphanum for date, datetime and text, num and -num for decimal and int
disjunctive decimal, int and text, facet only Whether multiple values can be selected for the facet
timeseries_precision date and datetime display precision of the field. Possible arguments are year, month and day for date, hour and minute for datetime
timerangeFilter date and datetime, facet only Whether to activate the timerange filter
unit int and decimal The unit of the field. Supported units are listed in the dedicated chapter
decimals decimal only The argument is the number of digits to appear after the decimal point
sortable text whether the field should be sortable in table view
multivalued text whether the field contains multiple values serparated by a character. The separator must be given as the argument
hierarchical text, facet only whether the field is hierarchical. The separator must be given as the argument

Description

give the complicated_field an elegant description

{
    "name": "description",
    "args": {
        "field": "complicated_field",
        "description": "Elegant description"
    }
}

Description are a mean to qualify and give some extra details about the content of the field. Descriptions are available when consulting the data.

Order

reorder the 3 fields first_field, second_field and third_field to be in the reverse order

{
    "name": "order",
    "args": [
        "third_field",
        "second_field",
        "first_field"
    ]
}

Fields are processed and displayed in a definite order, this configuration item can be used to change that order.

Delete

discard the useless_field

{
    "name": "delete",
    "args": {
        "field": "useless_field"
    }
}

Some fields present in the data source are not useful or redundant. This configuration item allows to discard these.

Units

Units are a way to describe the numeric values contained in a field. If a unit is set for a field, values are augmented with their symbol in the table view. See the annotation chapter to learn how to set a unit for a field.

Below is a comprehensive list of units supported by the platform.

Unit name Description
g Gram
kg Kilogram
t Tonne
oz Ounce
lb Pound
mm Millimeter
cm Centimeter
m Meter
km Kilometer
in Inch
ft Foot
mi Mile
mm2 Square millimeter
cm2 Square centimeter
m2 Square meter
km2 Square kilometer
ha Hectare
sqft Square feet
acre Acre
Euro
k€ Kilo Euro
$ Dollar
SAR SAR
£ British Pound
MXN Mexican Peso
seconds Seconds
minutes Minutes
hours Hours
days Days
months Months
years Years
Wh Watt hour
kWh Kilowatt hour
MWh Megawatt hour
GWh Gigawatt hour
TWh Terawatt hour
Toe Tonne of oil equivalent
bar Bar
mbar Millibar
Pa Pascal
db Decibel
W Watt
kW Kilowatt
MW Megawatt
GW Gigawatt
kVA Kilovolt-Ampere
A Ampere
kA Kiloampere
V Volt
kV Kilovolt
m/s Meter per second
km/s Kilometer per second
km/h Kilometer per hour
°C Celsius
°F Fahrenheit
cm3 Cubic centimeter
m3 Cubic meter
l Liter
hl Hectoliter
m3/s Cubic meter per second
L/s Liter per second
m3/h Cubic meter per hour
L/h Liter per hour
m3/d Cubic meter per day
L/d Liter per day
ppm Part per million
µg/L Microgram per liter
mg/L Milligram per liter
μg/m3 Microgram per cubic meter
g/L Gram per liter
kg/m3 Kilogram per cubic meter
% Percent
° Degree

Display a dataset fields specification stack

This endpoint is meant to return the list of field configuration items for a dataset. Since field configurations are exposed as processor objects, their unique identifiers are processor_uids.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/fields_specifications/

Example request

curl -XGET https://yourdomain.opendatasoft.com/api/management/datasets/da_abcdef/fields_specifications/
    -u username:password

Example response

[{
    "name": "type",
    "args": {
        "field": "badly_named_field",
        "type": "double"
    }
}, {
    "name": "rename",
    "args": {
        "from_name": "badly_named_field",
        "to_name": "right_name",
        "label": "Super easy to understand label"
    }
}, {
    "name": "annotate",
    "args": {
        "field": "right_name",
        "annotation": "decimals",
        "args": [5]
    }
}]

The payload lists the fields specification stack of the dataset. Please note that it reads in the order in which the configuration is applied.

Returns

The list of field configuration items, exposed as processor objects.

Add a field configuration item to a dataset

This endpoint is for adding a field configuration item for the dataset.

Definition

POST https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/da_abcdef/fields_specifications/

Example request

curl -XPOST https://yourdomain.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/fields_specifications/
    -u username:password \
    -d '{"name": "annotate", "args": {"field": "right_name", "annotation": "facet"}}'

Example response

{
    "processor_uid": "pr_abcdfe",
    "name": "annotate",
    "args": {
        "field": "right_name",
        "annotation": "facet"
    }
}

The endpoint takes a processor object (without its processor_uid, which will be automatically generated), creates a new field configuration item with the provided arguments and appends it at the end of the fields specification chain.

Parameters

Parameter Description
name
string
name of the field configuration item
args
object
parameters

Returns

The newly created field configuration item, exposed as a processor object.

Retrieve a field configuration item

This endpoint is meant to retrieve a field configuration item from a dataset, using its processor_uid.

Definition

GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/fields_specifications/{PROCESSOR_UID}

Example request

curl -XGET https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_abcdef/fields_specifications/pr_abcdfe
    -u username:password

Example response

{
    "processor_uid": "pr_abcdfe",
    "name": "annotate",
    "args": {
        "field": "right_name",
        "annotation": "facet"
    }
}

Returns

The requested field configuration item, exposed as a processor object.

Update a field configuration item

This endpoint is meant to update a field configuration item in place within the fields specification stack.

Definition

PUT https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/fields_specifications/{PROCESSOR_UID}

Example request

curl -XPUT https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_abcdef/fields_specifications/pr_abcdfe
    -u username:password \
    -d '{"name": "annotate", "args": {"field": "other_field", "annotation": "facet"}}'
}

Example response

{
    "processor_uid": "pr_abcdfe",
    "name": "annotate",
    "args": {
        "field": "other_field",
        "annotation": "facet"
    }
}

Parameters

Parameter Description
name
string
name of the field configuration item
args
object
parameters

Returns

The newly updated field configuration item, exposed as a processor object.

Delete a field configuration item

This endpoint is meant to delete a field configuration item from the fields specification stack of a dataset

Definition

DELETE https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/fields_specifications/{PROCESSOR_UID}

Example request

curl -XDELETE https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_abcdef/fields_specifications/pr_abcdfe
    -u username:password

Returns

On successful deletion, the endpoint returns a HTTP 204 without any content.

Pages

Pages can be used to write editorial content directly on the platform, build advanced dashboards and organize data portals.

Through the management API, it is possible to list, create, edit and delete pages as well as to configure pages visiblity on the portal.

The page object

Example object

{
    "slug": "my-page",
    "title": {
        "fr": "Titre de la page",
        "en": "Page title"
    },
    "description": "The page description",
    "layout": "single-main.html",
    "content": {
        "main": {
            "text": {
                "fr": "Contenu de la page",
                "en": "Page content"
            }
        }
    },
    "tags": [
        "tag1",
        "tag2"
    ],
    "restricted": true,
    "pushed_by_parent": false,
    "has_subdomain_copies": false,
    "created_at": "2018-02-20T16:30:35+00:00",
    "last_modified": "2018-02-20T16:30:35+00:00",
    "last_modified_user": {
        "username": "john.doe"
    },
    "author": {
        "username": "john.doe"
    }
}

Attributes

Attribute Description
slug
string
Human readable identifier used to generate the page URL
title
object
Internationalized page title
description
string
Page description
layout The HTML layout to use for this page. Possible values are single-main.html, main-left-col-right.html, homepage-searchbox.html, single-main-contact.html, dataset-catalog-overview.html, dataset-of-datasets.html, reuses.html, custom.html
content
object
Internationalized page content. The shape of the object depends on the chosen layout
tags
array of strings
List of strings used to classify and sort pages
restricted
boolean
Defines if the page is visible to every user who can explore the portal
created_at
datetime
Date when the page was created
last_modified
datetime
Date when the page was last edited
last_modified_user
user object
The user who last modified the page
author
user object
The user who created the page
pushed_by_parent
boolean
Inform if the page has been distributed by a parent domain
has_subdomain_copies
boolean
Inform if the page been distributed to any subdomain

Retrieve all pages

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages \
    -u username:password

Example response

{
    "items": [
        {
            "slug": "my-page",
            "title": {
                "fr": "Titre de la page",
                "en": "Page title"
            },
            "description": "The page description",
            "layout": "single-main.html",
            "content": {
                "main": {
                    "text": {
                        "fr": "Contenu de la page",
                        "en": "Page content"
                    }
                }
            },
            "tags": [
                "tag1",
                "tag2"
            ],
            "restricted": true,
            "pushed_by_parent": false,
            "has_subdomain_copies": false,
            "created_at": "2018-02-20T16:30:35+00:00",
            "last_modified": "2018-02-20T16:30:35+00:00",
            "last_modified_user": {
                "username": "john.doe"
            },
            "author": {
                "username": "john.doe"
            }
        },
        {...},
        {...}
    ],
    "rows": 10,
    "page": 1,
    "nhits": 42
}

This endpoint returns a paginated list of all the pages that can be edited by this user.

Parameters

Parameter Default Description
search
string
None Performs a full text search on the title, slug, description and tags attributes to filter the pages
rows
string
10 Number of items to return per page. Max value: 100
page
string
1 The page to return
sort
string
None Field on which to sort the returned objects

Returns

Returns a paginated list of page objects.

Retrieve a page

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page \
    -u username:password

Example response

{
    "slug": "my-page",
    "title": {
        "fr": "Titre de la page",
        "en": "Page title"
    },
    "description": "The page description",
    "layout": "single-main.html",
    "content": {
        "main": {
            "text": {
                "fr": "Contenu de la page",
                "en": "Page content"
            }
        }
    },
    "tags": [
        "tag1",
        "tag2"
    ],
    "restricted": true,
    "pushed_by_parent": false,
    "has_subdomain_copies": false,
    "created_at": "2018-02-20T16:30:35+00:00",
    "last_modified": "2018-02-20T16:30:35+00:00",
    "last_modified_user": {
        "username": "john.doe"
    },
    "author": {
        "username": "john.doe"
    }
}

This endpoint is for retrieving the page object with provided slug.

Parameters

No parameters.

Returns

Returns the page object.

Create a page

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages \
    -X POST \
    -u username:password \
    -d '{"slug": "my-page", "title": {"fr": "Titre de la page", "en": "Page title"}, "description": "The page description", "layout": "single-main.html", "content": {"main": {"text": {"fr": "Contenu de la page", "en": "Page content"}}}, "tags": ["tag1", "tag2"], "restricted": true}'

Example response

{
    "slug": "my-page",
    "title": {
        "fr": "Titre de la page",
        "en": "Page title"
    },
    "description": "The page description",
    "layout": "single-main.html",
    "content": {
        "main": {
            "text": {
                "fr": "Contenu de la page",
                "en": "Page content"
            }
        }
    },
    "tags": [
        "tag1",
        "tag2"
    ],
    "restricted": true,
    "pushed_by_parent": false,
    "has_subdomain_copies": false,
    "created_at": "2018-03-28T09:37:30.704488+00:00",
    "last_modified": "2018-03-28T09:37:30.704488+00:00",
    "last_modified_user": {
        "username": "john.doe"
    },
    "author": {
        "username": "john.doe"
    }
}

This endpoint is for creating a new page.

Parameters

No parameters.

Body

Parameter Description
slug
string
Human readable identifier used to generate the page's URL
title
object
Internationalized page title
description
string
Page description
layout The HTML layout to use for this page. Possible values are single-main.html, main-left-col-right.html, homepage-searchbox.html, single-main-contact.html, dataset-catalog-overview.html, dataset-of-datasets.html, reuses.html, custom.html
content
object
Internationalized page content. The shape of the object depends on the chosen layout
tags
array of strings
List of strings used to classify and sort pages
restricted
boolean
Defines if the page is visible to every user who can explore the portal. This parameter is only available if you have the permission to manage the pages' security

Returns

Returns the created page object.

Update a page

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page \
    -X PUT \
    -u username:password \
    -d '{"title": {"fr": "Nouveau titre de la page", "en": "New page title"}, "description": "The page description", "layout": "single-main.html", "content": {"main": {"text": {"fr": "Contenu de la page", "en": "Page content"}}}, "tags": ["tag1", "tag2"], "restricted": true}'

Example response

{
    "slug": "my-page",
    "title": {
        "fr": "Titre de la page",
        "en": "Page title"
    },
    "description": "The page description",
    "layout": "single-main.html",
    "content": {
        "main": {
            "text": {
                "fr": "Contenu de la page",
                "en": "Page content"
            }
        }
    },
    "tags": [
        "tag1",
        "tag2"
    ],
    "restricted": true,
    "pushed_by_parent": false,
    "has_subdomain_copies": false,
    "created_at": "2018-03-28T09:37:30.704488+00:00",
    "last_modified": "2018-03-28T09:37:30.704488+00:00",
    "last_modified_user": {
        "username": "john.doe"
    },
    "author": {
        "username": "john.doe"
    }
}

This endpoint is for updating an existing page object with provided slug.

Parameters

No parameters.

Body

Parameter Description
title
object
Internationalized page title
description
string
Page description
layout The HTML layout to use for this page. Possible values are single-main.html, main-left-col-right.html, homepage-searchbox.html, single-main-contact.html, dataset-catalog-overview.html, dataset-of-datasets.html, reuses.html, custom.html
content
object
Internationalized page content. The shape of the object depends on the chosen layout
tags
array of strings
List of strings used to classify and sort pages
restricted
boolean
Defines if the page is visible to every user who can explore the portal. This parameter is only available if you have the permission to manage the pages' security

Returns

Returns the updated page object.

Delete a page

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page \
    -X DELETE \
    -u username:password

This endpoint is for deleting an existing page object with provided slug.

Parameters

No parameters.

Returns

A HTTP response with no content and status code 204.

Delete multiple pages

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/ \
    -X DELETE \
    -u username:password \
    -d '[{"slug": "my-page"}, {...}, , {...}]'

Example response

[
    {
        "slug": "my-page",
        "title": {
            "fr": "Titre de la page",
            "en": "Page title"
        },
        "description": "The page description",
        "layout": "single-main.html",
        "content": {
            "main": {
                "text": {
                    "fr": "Contenu de la page",
                    "en": "Page content"
                }
            }
        },
        "tags": [
            "tag1",
            "tag2"
        ],
        "restricted": true,
        "pushed_by_parent": false,
        "has_subdomain_copies": false,
        "created_at": "2018-02-20T16:30:35+00:00",
        "last_modified": "2018-02-20T16:30:35+00:00",
        "last_modified_user": {
            "username": "john.doe"
        },
        "author": {
            "username": "john.doe"
        }
    },
    {...},
    {...}
]

This endpoint is for deleting multiple pages.

Parameters

No parameters.

Body

This endpoint accepts a list of objects containing the following parameters:

Parameter Description
slug
string
The page's slug to be deleted

Returns

The list of deleted page objects.

Pages security

The page security is the set of rules that defines who (which users / groups) can explore or edit a given page.

It is defined through 2 variables:

If the page is set as restricted, then the page will only appear in the portal for users who have a ruleset declared for them, either directly or through a group. Other users won't have any access to the page.

Rulesets can also give users permission to edit the page and manage its security.

The page security API in a nutshell

User level page security ruleset

/pages/{PAGE_SLUG}/security/users

/pages/{PAGE_SLUG}/security/users/{USERNAME}

Group level page security ruleset

/pages/{PAGE_SLUG}/security/groups

/pages/{PAGE_SLUG}/security/groups/{GROUP_ID}

The page security ruleset object

Example object

{
    "permissions": [],
    "created_at": "2018-03-28T13:17:13.302632+00:00",
    "updated_at": "2018-03-28T13:17:13.302632+00:00",
    "user": {
        "username": "john.doe"
    },
    "group": {
        "group_id": "your.group"
    },
    "page": {
        "domain": {
            "domain_id": "yourdomain"
        },
        "slug": "my-page"
    }
}

Attributes

Attribute Description
permissions
array of strings
List of special permissions granted to the target. Possible values are edit_page
created_at
datetime
Date when the ruleset was created
updated_at
datetime
Date when the ruleset was last edited
page
page object
The page targeted by this ruleset
user
user object
The user targeted by this ruleset.
Only available for user-level rulesets
group
group object
The group targeted by this ruleset.
Only available for group-level rulesets

Retrieve all user level page security rulesets

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/users

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/users \
    -u username:password

Example response

[
    {
      "permissions": [],
      "created_at": "2018-03-28T13:17:13.302632+00:00",
      "updated_at": "2018-03-28T13:17:13.302632+00:00",
      "user": {
          "username": "john.doe"
      },
      "page": {
          "domain": {
              "domain_id": "yourdomain"
          },
          "slug": "my-page"
      }
    },
    {...},
    {...}
]

This endpoint is for retrieving all rulesets defined for the page with provided slug.

Parameters

No parameters.

Returns

Returns a list of page security ruleset objects.

Retrieve a user level page security ruleset

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/users/{USERNAME}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/users/john.doe \
    -u username:password

Example response

{
    "permissions": [],
    "created_at": "2018-03-28T13:17:13.302632+00:00",
    "updated_at": "2018-03-28T13:17:13.302632+00:00",
    "user": {
        "username": "john.doe"
    },
    "page": {
        "domain": {
            "domain_id": "yourdomain"
        },
        "slug": "my-page"
    }
}

This endpoint is for retrieving the user level security ruleset object with provided username.

Parameters

No parameters.

Returns

Returns the user level page security ruleset object.

Create a user level page security ruleset

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/users

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/users \
    -X POST \
    -u username:password \
    -d '{"permissions": ["edit_page"], "user": {"username": "john.doe"}}'

Example response

{
    "permissions": ["edit_page"],
    "created_at": "2018-03-28T13:17:13.302632+00:00",
    "updated_at": "2018-03-28T13:17:13.302632+00:00",
    "user": {
        "username": "john.doe"
    },
    "page": {
        "domain": {
            "domain_id": "yourdomain"
        },
        "slug": "my-page"
    }
}

This endpoint is for creating a new user level security ruleset.

Parameters

No parameters

Body

Parameter Description
permissions
array of strings
List of special permissions granted to the user. Possible values are edit_page
user
user object
The user targeted by this ruleset

Returns

Returns the created user level page security ruleset object.

Update a user level page security ruleset

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/users/{USERNAME}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/users/john.doe \
    -X PUT \
    -u username:password \
    -d '{"permissions": ["edit_page"]}'

Example response

{
    "permissions": ["edit_page"],
    "created_at": "2018-03-28T13:17:13.302632+00:00",
    "updated_at": "2018-03-28T13:17:13.302632+00:00",
    "user": {
        "username": "john.doe"
    },
    "page": {
        "domain": {
            "domain_id": "yourdomain"
        },
        "slug": "my-page"
    }
}

This endpoint is for updating an existing user level page security ruleset object with provided username

Parameters

No parameters

Body

Parameter Description
permissions
array of strings
List of special permissions granted to the user. Possible values are edit_page

Returns

Returns the updated user level page security ruleset object.

Delete a user level page security ruleset

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/users/{USERNAME}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/users/john.doe \
    -X DELETE \
    -u username:password

This endpoint is for deleting an existing user level security ruleset with provided username.

Parameters

No parameters.

Returns

A HTTP response with no content and status code 204.

Retrieve all group level page security rulesets

Definition

GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/groups

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/groups \
    -u username:password

Example response

[
    {
      "permissions": [],
      "created_at": "2018-03-28T13:17:13.302632+00:00",
      "updated_at": "2018-03-28T13:17:13.302632+00:00",
      "group": {
          "group_id": "your.group"
      },
      "page": {
          "domain": {
              "domain_id": "yourdomain"
          },
          "slug": "my-page"
      }
    },
    {...},
    {...}
]

This endpoint is for retrieving all rulesets defined for the page with provided slug.

Parameters

No parameters.

Returns

Returns a list of page security ruleset objects.

Create a group level page security ruleset

Definition

POST https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/groups

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/groups \
    -X POST \
    -u username:password \
    -d '{"permissions": ["edit_page"], "group": {"group_id": "your.group"}}'

Example response

{
    "permissions": ["edit_page"],
    "created_at": "2018-03-28T13:17:13.302632+00:00",
    "updated_at": "2018-03-28T13:17:13.302632+00:00",
    "group": {
        "group_id": "your.group"
    },
    "page": {
        "domain": {
            "domain_id": "yourdomain"
        },
        "slug": "my-page"
    }
}

This endpoint is for creating a new group level security ruleset.

Parameters

No parameters.

Body

Parameter Description
permissions
array of strings
List of special permissions granted to the group. Possible values are edit_page
group
group object
The group targeted by this ruleset

Returns

Returns the created group level page security ruleset object.

Update a group level page security ruleset

Definition

PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/groups/{GROUP_ID}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/groups/your.group \
    -X PUT \
    -u username:password \
    -d '{"permissions": ["edit_page"]}'

Example response

{
    "permissions": ["edit_page"],
    "created_at": "2018-03-28T13:17:13.302632+00:00",
    "updated_at": "2018-03-28T13:17:13.302632+00:00",
    "group": {
        "group_id": "your.group"
    },
    "page": {
        "domain": {
            "domain_id": "yourdomain"
        },
        "slug": "my-page"
    }
}

This endpoint is for updating an existing group level page security ruleset object with provided group_id.

Parameters

No parameters.

Body

Parameter Description
permissions
array of strings
List of special permissions granted to the group. Possible values are edit_page

Returns

Returns the updated group level page security ruleset object.

Delete a group level page security ruleset

Definition

DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/pages/{PAGE_SLUG}/security/groups/{GROUP_ID}

Example request

curl https://yourdomain.opendatasoft.com/api/management/v2/pages/my-page/security/groups/your.group \
    -X DELETE \
    -u username:password

This endpoint is for deleting an existing group level security ruleset with provided group_id.

Parameters

No parameters.

Returns

A HTTP response with no content and status code 204.

Form widgets

A few endpoints in the API return definitions along with their objects in order to help you build correct requests. These definitions are specifications your objects must conform to in order to be accepted by the API.

Some of these API will contain a widget attribute that contains all you need to generate an HTML input that will match the object's structure.

The form object

Example object

{
    "type": "text",
    "label": "Language",
    "help_text": "",
    "choices": [
        ["aa", "Afar"],
        ["ab", "Abkhazian"],
        ["ae", "Avestan"],
        ["af", "Afrikaans"],
        [...],
        [...]
    ],
    "widget": {
        "type": "select"
    }
}

An object describing exactly the type of data the related object can accept and providing the expected representation in a form.

Attributes

Attribute Description
name
string
Identifier of the object
type
string
Nature of the object.
Possible values are text, multitext, html, date and datetime
label
string
Plain name of the object depending of the language
widget
widget object
Characteristics of the expected rendered UI component for the object
choices
array
text and multitext only
List of all accepted values by the object, any other value will be rejected.
May be an array of strings or an array of 2-item arrays, where the first item is the actual accepted value and the second its label.
help_text
string
Informational text describing the constraints and uses of the form object

The widget object

List of all widget objects:

Common attributes

Attribute  Description
type
string
The widget's type
Accepted values are textinput, select, datalist, multitextinput, multidatalist, tags, datetimeinput and geographicarea

The datalist widget

Example object

{
    "type": "text",
    "label": "License",
    "help_text": "",
    "widget": {
        "type": "datalist",
        "suggest_values": [
            "Licence Ouverte (Etalab)",
            "Licence Ouverte v2.0 (Etalab)",
            "Open Government Licence v3.0",
            "Open Database License (ODbL)",
            "Public Domain",
            "CC BY",
            "CC BY-ND",
            "CC BY-NC-ND",
            "CC BY-NC",
            "CC BY-NC-SA",
            "CC BY-SA",
            "CC BY-IGO"
        ]
    }
}

Example HTML widget

<label for="license">License</label>
<input type="text" id="license" name="license" list="license_list">
<datalist id="license_list">
    <option value="Licence Ouverte (Etalab)">
    <option value="Licence Ouverte v2.0 (Etalab)">
    <option value="Open Government Licence v3.0">
    <option value="Open Database License (ODbL)">
    <option value="Public Domain">
    <option value="CC BY">
    <option value="CC BY-ND">
    <option value="CC BY-NC-ND">
    <option value="CC BY-NC">
    <option value="CC BY-NC-SA">
    <option value="CC BY-SA">
    <option value="CC BY-IGO">
</datalist>

The datalist widget will render as a text input with an autocomplete feature. If the suggest_values attributes is set, then a simple html datalist is enough.

Attribute  Description
suggest_url
string
The URL of a distant service providing values based on the partial text in the input (e.g. Algolia)
suggest_values
array of strings
A list of default values

The dateinput widget

Example object

{
    "type": "date",
    "label": "Created",
    "help_text": "",
    "widget": {
        "type": "dateinput"
    }
}

Example HTML widget

<label for="created">Created</label>
<input id="created" type="date-local">

The dateinput widget will render as a date-local input.

The datetimeinput widget

Example object

{
    "type": "datetime",
    "label": "Modified",
    "help_text": "",
    "widget": {
        "type": "datetimeinput"
    }
}

Example HTML widget

<label for="modified">Modified</label>
<input id="modified" type="datetime-local">

The datetimeinput widget will render as a datetime-local input.

The multidatalist widget

Example object

{
    "type": "multitext",
    "label": "Theme",
    "help_text": "",
    "widget": {
        "type": "multidatalist",
        "suggest_values": [
            "Health",
            "Culture, Heritage",
            "Education, Training, Research, Teaching",
            "Environment",
            "Transport, Movements",
            "Spatial planning, Town planning, Buildings, Equipment, Housing",
            "Economy, Business, SME, Economic development, Employment",
            "Administration, Government, Public finances, Citizenship",
            "Justice, Safety, Police, Crime",
            "Sports, Leisure",
            "Accommodation, Hospitality Industry",
            "Services, Social"
        ]
    }
}

Example HTML widget

<label for="theme">Theme</label>
<input id="theme" type="text" placeholder="New theme..." list="theme_list">
<button>Add theme</button>
<ul>
    <li><input type="text" value="Sports, Leisure" list="theme_list"><button>remove</button></li>
    <li><input type="text" value="Health" list="theme_list"><button>remove</button></li>
</ul>
<datalist id="theme_list">
    <option value="Health">
    <option value="Culture, Heritage">
    <option value="Education, Training, Research, Teaching">
    <option value="Environment">
    <option value="Transport, Movements">
    <option value="Spatial planning, Town planning, Buildings, Equipment, Housing">
    <option value="Economy, Business, SME, Economic development, Employment">
    <option value="Administration, Government, Public finances, Citizenship">
    <option value="Justice, Safety, Police, Crime">
    <option value="Sports, Leisure">
    <option value="Accommodation, Hospitality Industry">
    <option value="Services, Social">
</datalist>

The multidatalist widget will render as multiple text inputs with an autocomplete feature, with the possibility to remove and add more inputs.

Attributes

Common attributes only.

The multiselect widget

Example object

 {
    "type": "multitext",
    "label": "Type",
    "help_text": "",
    "choices": [
        "Spatial data set",
        "Spatial data set series",
        "Spatial data service"
    ],
    "widget": {
        "type": "multiselect"
    }
}

Example HTML widget

<label for="type">Type</label>
<select id="type">
    <option>Spatial data set</option>
    <option>Spatial data set series</option>
    <option>Spatial data service</option>
</select>
<button>Add theme</button>
<ul>
    <li>
        <select value="Spatial data set series">
            <option>Spatial data set</option>
            <option>Spatial data set series</option>
            <option>Spatial data service</option>
        </select>
        <button>remove</button>
    </li>
    <li>
        <select value="Spatial data set">
            <option>Spatial data set</option>
            <option>Spatial data set series</option>
            <option>Spatial data service</option>
        </select>
        <button>remove</button>
    </li>
</ul>

The multiselect widget will render as multiple selects components, with the possibility to remove, change and add more values.

The multitextinput widget

Example object

{
    "type": "multitext",
    "label": "Attributions",
    "help_text": "",
    "widget": {
        "type": "multitextinput"
    }
}

Example HTML widget

<label for="attributions">Attributions</label>
<input id="attributions" type="text" placeholder="New attribution...">
<button>Add attribution</button>
<ul>
    <li><input type="text" value="First attribution"><button>remove</button></li>
    <li><input type="text" value="Second attribution"><button>remove</button></li>
    <li><input type="text" value="Third attribution"><button>remove</button></li>
</ul>

The multitextinput widget will render as multiple simple text inputs, with the possibility to remove and add more inputs.

The richtextinput widget

Example object

{
    "type": "html",
    "label": "Description",
    "help_text": "",
    "widget": {
        "type": "richtextinput"
    }
}

Example HTML widget

<label for="description">Description</label>
<!-- redactor is a js library that transforms a textarea into a wysiwyg editor -->
<textarea id="description" redactor value="<p>Lorem ipsum dolor sit amet</p>"></textarea>

The richtextinput message will render as a rich text editor, preferably a WYSIWYG (What You See Is What You Get) one.

The select widget

Example object

{
    "type": "text",
    "label": "Language",
    "help_text": "",
    "choices": [
        ["aa", "Afar"],
        ["ab", "Abkhazian"],
        ["ae", "Avestan"],
        ["af", "Afrikaans"],
        [...],
        [...]
    ],
    "widget": {
        "type": "select"
    }
}

Example HTML widget

<label for="language">Language</label>
<select id="language">
    <option value="aa">Afar</option>
    <option value="ab">Abkhazian</option>
    <option value="ae">Avestan</option>
    <option value="af">Afrikaans</option>
    ...
</select>

The select widget will render as a simple select element.

Options of this element must match the choices defined in the parent form object.

The tags widget

Example object

{
    "type": "multitext",
    "label": "Keyword",
    "help_text": "Hit Enter after each keyword",
    "widget": {
        "type": "tags",
        "suggest_url": "/api/management/1.0/metadata_templates/default/keyword/suggest"
    }
}

Example HTML widget

<label for="keyword">Keyword</label>
<input type="text" id="keyword" placeholder="Type keyword">
<button>Add keyword</button>
<p>Hit enter after each keyword</p>
<ul>
    <li>
        Keyword1 <button>remove</button>
    </li>
    <li>
        Keyword2 <button>remove</button>
    </li>
</ul>

The tags widget will render as an editable list of tags. If possible, the input area where the user enters their new tag should autocomplete with existing values to enhance consistency.

Attribute  Description
suggest_url
string
The URL of a distant service providing values based on the partial text in the input (e.g. Algolia)
suggest_values
array of strings
A list of default values

The textinput widget

Example object

{
    "type": "text",
    "label": "Title",
    "help_text": "",
    "widget": {
        "type": "textinput"
    }
}

Example HTML widget

<label for="title">Title</label>
<input type="text" id="title">

The textinput widget will render as a simple text input.

Misc objects

The quota object

The quota object defines an upper limit within a given timeframe.

Example object

10000 api calls per day

{
    "limit": 10000,
    "unit": "day"
}

Attributes

Attribute Description
limit
integer
Upper limit
unit
string
Timeframe.
Possible values are hour, day, month