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 using an
Authorization: Apikey <API_KEY>
header
curl --header 'Authorization: Apikey 7f5e144f079444b20fd360cf77e9fcbe6d10b10a378d995c208796e3
https://mydomain.opendatasoft.com/api/management/v2/datasets
After generating an API key and assigning it appropriate permissions, you can use this API key to make authenticated requests. It is good practice to pass the API key to the Authorization
header in the following format:
Authorization: Apikey <API_KEY>
Alternatively, you can pass the API key as a query parameter in the following format:
apikey=<API_KEY>
Replace <API_KEY>
with your API key.
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):
- the username and password are combined with a single colon (
:
) - the resulting string is encoded using a variant of Base64
- the authorization method and a space (e.g. "Basic ") is then prepended to the encoded string
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:
if the user doesn't have an Opendatasoft account, the e-mail provides them a link to create their account and choose a password,
this invitation links the new user or existing user to this domain, allowing domain administrator to grant them permissions to perform specific actions.
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:
- list users linked to the domain,
- lookup a specific user,
- invite users on the domain (via an e-mail address),
- grant users permissions, quotas and limits on the domain,
- add or remove them from groups,
- delete users from the domain.
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:
- list groups,
- lookup a specific group,
- create groups,
- grant groups permissions, quotas and limits,
- list, add and delete users in groups,
- delete groups
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, that grant rights to a user, group or API key on the whole domain,
- dataset level permissions, that grant rights to a user, group or API key on a specific dataset,
- page level permissions, that grant rights to a user, group or API key on a specific page.
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:
- domain permission:
create_dataset
oredit_dataset
- any dataset permission:
edit_dataset
orpublish_dataset
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:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Delete
DELETE /api/management/v2/datasets/<dataset_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Abort Action
PUT /api/management/v2/datasets/<dataset_uid>/abort/
Requires one of the following:
- domain permission:
edit_dataset
andpublish_dataset
- current dataset permission: (
edit_dataset
and domain:publish_dataset
) orpublish_dataset
Dataset Attachements Index
GET /api/management/v2/datasets/<dataset_uid>/attachments/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Attachements Create
POST /api/management/v2/datasets/<dataset_uid>/attachments/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Attachment Lookup
GET /api/management/v2/datasets/<dataset_uid>/attachments/<attachment_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Attachment Delete
DELETE /api/management/v2/datasets/<dataset_uid>/attachments/<attachment_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Change Index
GET /api/management/v2/datasets/<dataset_uid>/changes/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Attachment Download
GET /api/management/v2/datasets/<dataset_uid>/download_attachment/<attachment_uid>
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset System Processor Index
GET /api/management/v2/datasets/<dataset_uid>/fields_specifications/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset System Processor Create
POST /api/management/v2/datasets/<dataset_uid>/fields_specifications/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset System Processor Lookup
GET /api/management/v2/datasets/<dataset_uid>/fields_specifications/<processor_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset System Processor Update
PUT /api/management/v2/datasets/<dataset_uid>/fields_specifications/<processor_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Processor Guess Params
POST /api/management/v2/datasets/<dataset_uid>/guess_processor_params/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Metadata Index
GET /api/management/v2/datasets/<dataset_uid>/metadata/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Metadata Lookup
GET /api/management/v2/datasets/<dataset_uid>/metadata/<template_name>/<metadata_name>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Metadata Update
PUT /api/management/v2/datasets/<dataset_uid>/metadata/<template_name>/<metadata_name>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Metadata Delete
DELETE /api/management/v2/datasets/<dataset_uid>/metadata/<template_name>/<metadata_name>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Processor Index
GET /api/management/v2/datasets/<dataset_uid>/processors/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Processor Create
POST /api/management/v2/datasets/<dataset_uid>/processors/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Processor Lookup
GET /api/management/v2/datasets/<dataset_uid>/processors/<processor_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Processor Update
PUT /api/management/v2/datasets/<dataset_uid>/processors/<processor_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Publish Action
PUT /api/management/v2/datasets/<dataset_uid>/publish/
Requires one of the following:
- domain permission:
edit_dataset
andpublish_dataset
- current dataset permission: (
edit_dataset
and domain:publish_dataset
) orpublish_dataset
Dataset Unsaved Resource Preview
POST /api/management/v2/datasets/<dataset_uid>/resource_preview/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Resource Index
GET /api/management/v2/datasets/<dataset_uid>/resources/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Resource Create
POST /api/management/v2/datasets/<dataset_uid>/resources/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Resource Lookup
GET /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Resource Update
PUT /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Resource Delete
DELETE /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Resource Download
GET /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/download
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Resource Preview
GET /api/management/v2/datasets/<dataset_uid>/resources/<resource_uid>/preview/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Restore Change Action
PUT /api/management/v2/datasets/<dataset_uid>/restore_change/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Schedule Index
GET /api/management/v2/datasets/<dataset_uid>/schedules/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Schedule Create
POST /api/management/v2/datasets/<dataset_uid>/schedules/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Schedule Lookup
GET /api/management/v2/datasets/<dataset_uid>/schedules/<schedule_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
orpublish_dataset
Dataset Schedule Update
PUT /api/management/v2/datasets/<dataset_uid>/schedules/<schedule_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Schedule Delete
DELETE /api/management/v2/datasets/<dataset_uid>/schedules/<schedule_uid>/
Requires one of the following:
- domain permission:
edit_dataset
- current dataset permission:
edit_dataset
Dataset Access Policy Lookup
GET /api/management/v2/datasets/<dataset_uid>/security/access_policy/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Access Policy Update
PUT /api/management/v2/datasets/<dataset_uid>/security/access_policy/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Default Security Lookup
GET /api/management/v2/datasets/<dataset_uid>/security/default/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Default Security Update
PUT /api/management/v2/datasets/<dataset_uid>/security/default/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Group Security Index
GET /api/management/v2/datasets/<dataset_uid>/security/groups/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Group Security Create
POST /api/management/v2/datasets/<dataset_uid>/security/groups/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Group Security Lookup
GET /api/management/v2/datasets/<dataset_uid>/security/groups/<group_id>/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Group Security Update
PUT /api/management/v2/datasets/<dataset_uid>/security/groups/<group_id>/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Group Security Delete
DELETE /api/management/v2/datasets/<dataset_uid>/security/groups/<group_id>/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset User Security Index
GET /api/management/v2/datasets/<dataset_uid>/security/users/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset User Security Create
POST /api/management/v2/datasets/<dataset_uid>/security/users/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset User Security Lookup
GET /api/management/v2/datasets/<dataset_uid>/security/users/<username>/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset User Security Update
PUT /api/management/v2/datasets/<dataset_uid>/security/users/<username>/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset User Security Delete
DELETE /api/management/v2/datasets/<dataset_uid>/security/users/<username>/
Requires one of the following:
- domain permission:
edit_dataset
andmanage_dataset
- current dataset permission:
edit_dataset
andmanage_dataset
Dataset Status
GET /api/management/v2/datasets/<dataset_uid>/status/
Requires one of the following:
- domain permission:
edit_dataset
andpublish_dataset
- current dataset permission: (
edit_dataset
and domain:publish_dataset
) orpublish_dataset
Dataset Unpublish Action
PUT /api/management/v2/datasets/<dataset_uid>/unpublish/
Requires one of the following:
- domain permission:
edit_dataset
andpublish_dataset
- current dataset permission: (
edit_dataset
and domain:publish_dataset
) orpublish_dataset
Catalog Export
GET /api/management/v2/export_datasets/<export_format>/
Requires one of the following:
- domain permission:
create_dataset
oredit_dataset
- any dataset permission:
edit_dataset
orpublish_dataset
Extractors Index
GET /api/management/v2/extractors/
Requires one of the following:
- domain permission:
create_dataset
oredit_dataset
- any dataset permission:
edit_dataset
System Processor Index
GET /api/management/v2/fields_specifications/
Requires one of the following:
- domain permission:
create_dataset
oredit_dataset
- any dataset permission:
edit_dataset
Guess Extractor Params
POST /api/management/v2/guess_extractor_params/
Requires one of the following:
- domain permission:
create_dataset
oredit_dataset
- any dataset permission:
edit_dataset
Guess Extractors
POST /api/management/v2/guess_extractors/
Requires one of the following:
- domain permission:
create_dataset
oredit_dataset
- any dataset permission:
edit_dataset
Processor Index
GET /api/management/v2/processors/
Requires one of the following:
- domain permission:
create_dataset
oredit_dataset
- any dataset permission:
edit_dataset
List Harvesters
GET /api/management/v2/harvesters/
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Harvester Lookup
GET /api/management/v2/harvesters/<harvester_id>
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Delete a Harvester
DELETE /api/management/v2/harvesters/<harvester_id>
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Update a Harvester
PUT /api/management/v2/harvesters/<harvester_id>
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Preview Harvester results
GET /api/management/v2/harvesters/<harvester_id>/preview/
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
View Harvester errors
GET /api/management/v2/harvesters/<harvester_id>/preview/
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Start a Harvester
PUT /api/management/v2/harvesters/<harvester_id>/start/
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Publish the datasets attached to a Harvester
PUT /api/management/v2/harvesters/<harvester_id>/publish/
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Unpublish the datasets attached to a Harvester
PUT /api/management/v2/harvesters/<harvester_id>/unpublish/
Requires all of the following:
- domain permission:
create_dataset
,edit_dataset
andpublish_dataset
Quotas and limits
Users and API keys can be limited in their usage in two ways:
- quotas are the maximum number of requests a user or API key can perform each day,
- limits are the maximum number of datasets a user can create, and the maximum number of records that can be published by the user.
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:
- a unique identifier
- a URL for use in the platform
- the file name
- a set of file properties
- a creation date
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:
- the actual data available on the portal (not available via the management API)
- metadata like a title, a description and keywords describing the data, so users can discover it in the portal's catalog
- configurations for processors, visualisation and security, which define the way data will be processed by the platform and made visible to users
Through the management API, it is possible to:
- create datasets
- attach resources to datasets
- configure datasets processing pipeline, visualisations and security attributes
- publish datasets
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:
- the
dataset_uid
that is automatically set, and will never change through the lifetime of the dataset. - the
dataset_id
, that can be chosen during dataset creation or changed on an unpublished dataset
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 expandable |
Current status of the object |
changes Array of dataset change objects expandable |
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 expandable |
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) |
rows string |
10 | Number of items to return per page. Max value: 100 |
page string |
1 | Request a specific page of results |
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:
- a single state at a time
- the list of possible states, fully known
- the list of all transitions, fully known, each with the actions and conditions that can trigger them
Here is the full state machine description.
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 expandable |
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 expandable |
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
- unpublish a dataset
- abort the processing of a dataset
- delete a dataset
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:
- a processor: when a value is invalid or an operation failed
- a type conversion: when a value cannot be converted. For example the string "s" converted to an integer.
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:
- a unique identifier
- a reference to the dataset that changed
- a reference to the user who created the new state
- the day and time at which the change occured
- the difference between the old and the new state of the dataset
- the sections in which the change happened
Attributes
Attribute | Description |
---|---|
change_uid string |
Unique identifier for the change |
dataset dataset object expandable |
Dataset targeted by the change expandable |
user user object expandable |
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, and a parameter 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": ";"
}
}
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 |
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": ";"
}
}, {...}]
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": ";"}}'
Example response
{
"resource_uid": "re_abcdef",
"url": "odsfile://resource.csv",
"title": "My Awesome Data File",
"type": "csvfile",
"params": {
"headers_first_row": false,
"separator": ";"
}
}
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": ";"
}
}
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": ";"}}'
Example response
{
"resource_uid": "re_abcdef",
"url": "odsfile://resource.csv",
"title": "My Awesome Data File",
"type": "csvfile",
"params": {
"headers_first_row": false,
"separator": ";"
}
}
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.
Download a resource
This API endpoint is meant to download the file used by a resource specified with its UID.
Definition
GET https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/resources/{RESOURCE_UID}/download
Example request
curl -XGET https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/resources/{RESOURCE_UID}/download
-u username:password \
The resource must be a file uploaded to the platform: its URL uses the odsfile://
URL scheme.
This endpoint takes a resource UID in its URL path.
Parameters
No parameters
Returns
The file used by the resource with the specified UID
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": ";"}}'
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 metadata template object |
Group of the current object |
definition form object expandable |
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
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.
Update multiple metadata values at once
Definition
PUT https://{YOURDOMAIN}.opendatasoft.com/api/management/v2/datasets/{DATASET_UID}/metadata/
Example request
curl https://yourdomain.opendatasoft.com/api/management/v2/datasets/da_XXXXXX/metadata/ \
-u username:password \
-X PUT \
-d '{"metas": [{"template_name": "default", "metadata_name": "title", "override_remote_value": false, "value": "My Dataset"}, \
{"template_name": "default", "metadata_name": "keyword", "override_remote_value": false, "value": ["keyword1", "keyword"]}]}'
Example response
[
{
"name": "title",
"template": {
"name": "default",
"label": "Standard",
"purpose": "general"
},
"definition": {},
"value": "My Dataset",
"remote_value": null,
"override_remote_value": false
},
{
"name": "keyword",
"template": {
"name": "default",
"label": "Standard",
"purpose": "general"
},
"definition": {},
"value": [
"keyword1",
"keyword"
],
"remote_value": null,
"override_remote_value": false
}
]
Send a list of metadata values to update all of them at once.
Parameters
A JSON object passed in the request's body containing a list of metadata names and values. See metadata object for reference on the metadata parameters.
General case
Parameter | Description |
---|---|
template_name |
The metadata template name, for instance default . |
metadata_name |
The metadata name, for instance title . |
value |
The new metadata value. Must conform to the metadata definition's type. Can be null . |
override_remote_value boolean |
Applies only to federated or harvested datasets. Flag indicating whether the indexed value is value or remote_value . If false the value of value is always deleted. |
Returns
All of the dataset's metadata objects reflecting the updated values.
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:
- a general access policy that sets whether the dataset is accessible to anyone or just a few specific users
- specific rulesets for users and groups
- a default ruleset that applies to anybody else
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
GET
retrieve the default security rulesetPUT
update the default security rulesetDELETE
reset the default security ruleset
User level security ruleset
/dataset/{DATASET_UID}/security/users
/dataset/{DATASET_UID}/security/users/{USERNAME}
GET
Retrieve a user level security rulesetPUT
Update a user level security rulesetDELETE
Delete a user level security ruleset
Group level security ruleset
/dataset/{DATASET_UID}/security/groups
/dataset/{DATASET_UID}/security/groups/{group_id}
GET
Retrieve a group level security rulesetPUT
Update a group level security rulesetDELETE
Delete a group level security ruleset
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:
domain
restricted
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:
- a specific user
- a specific group
- anyone who has access to the portal and who isn't affected by either a user-level or a group-level ruleset
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 expandable |
The user targeted by this ruleset. Only available for user-level rulesets. |
group group object expandable |
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>
Harvesters
Harvesters provide a way for administrators to create and update an important number of datasets by importing them from an external source such as a CSW catalog or an ArcGIS service, among many others. Your user and your API key need the permissions "create_dataset", "edit_dataset" and "publish_dataset".
Through the management API, it is possible to:
- create a harvester
- start a harvester
- publish the datasets attached to a harvester
- unpublish the datasets attached to a harvester
- delete a harvester and optionally delete its datasets
List harvesters
Definition
GET https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/harvesters/
Example request
curl https://yourdomain.opendatasoft.com/api/management/v2/harvesters/ \
-u username:password
Example response
[
{
"status": "new",
"fetcher": {
"type": "ods",
"label": "Opendatasoft",
"description": "Harvester description",
"parameters": [
{
"is_mandatory": false,
"type": "string",
"name": "api_key",
"label": "Api key"
},
{
"is_mandatory": false,
"type": "boolean",
"name": "delete",
"label": "Delete datasets removed from remote portal"
},
{
"is_mandatory": true,
"type": "string",
"name": "domain_id",
"label": "Domain (ID or URL)"
},
{
"is_mandatory": false,
"type": "string",
"name": "forced_metas",
"label": "Forced metadata as a JSON object"
},
{
"is_mandatory": false,
"type": "string",
"name": "refines",
"label": "Refines"
},
{
"is_mandatory": false,
"type": "boolean",
"name": "restrict_visibility",
"label": "Make the visibility of newly harvested datasets restricted (does not update visibility of existing datasets)"
}
]
},
"last_modified_by": "john.doe",
"schedules": null,
"errors": {
"resources": 0,
"harvester": 0
},
"name": "My Harvester",
"harvester_id": "my-harvester",
"last_modified_at": "2019-07-19T14:56:25+00:00",
"version": 1,
"params": {
"restrict_visibility": true
},
"created_at": "2019-07-19T14:56:25+00:00",
"counters": {
"attached": 0,
"published": 0
}
}
]
This endpoint lists all the harvesters on the domain, including their parameters.
Start a harvester
Definition
PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/harvesters/<harvester_id>/start/
Example request
curl https://yourdomain.opendatasoft.com/api/management/v2/harvesters/my_harvester/start/ \
-X PUT \
-u username:password
This endpoint will start a harvester. If it succeeds, it will return a status code 200 with the harvester details.
Publish a harvester's datasets
Definition
PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/harvesters/<harvester_id>/publish/
Example request
curl https://yourdomain.opendatasoft.com/api/management/v2/harvesters/my_harvester/publish/ \
-X PUT \
-u username:password
This endpoint will publish all datasets attached to the harvester. If it succeeds, it will return a status code 200 with the harvester details.
Unpublish a harvester's datasets
Definition
PUT https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/harvesters/<harvester_id>/unpublish/
Example request
curl https://yourdomain.opendatasoft.com/api/management/v2/harvesters/my_harvester/unpublish/ \
-X PUT \
-u username:password
This endpoint will unpublish all datasets attached to the harvester. If it succeeds, it will return a status code 200 with the harvester details.
Delete a harvester (and its datasets)
Definition
DELETE https://{DOMAIN_ID}.opendatasoft.com/api/management/v2/harvesters/<harvester_id>/?delete_attached_datasets=0
Example request
curl https://yourdomain.opendatasoft.com/api/management/v2/harvesters/my_harvester/?delete_attached_datasets=0 \
-X DELETE \
-u username:password
This endpoint will delete the harvester and all its attached datasets if delete_attached_datasets=1
.
If you set delete_attached_datasets=0
, then the harvester will be deleted but the attached datasets will be kept.
If it succeeds, it will returns a status code 204 with an empty body.
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"
}
}
Example object with label
{
"processor_uid" : "pr_mgnlcn",
"name" : "expression",
"label" : "my_column > or < 0",
"args" : {
"output_field" : "result",
"expression" : "{{my_column > 0 ? 'positive' : 'negative'}}"
}
}
Attribute | Description |
---|---|
name string |
Name of the processor |
args object |
Processor configuration |
processor_uid string |
Unique identifier for the processor |
label string |
(optional) Label of 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/v2/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": "timeserie_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 |
timeserie_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
andthird_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_uid
s.
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",
"template": "custom.html",
"content": {
"html": {
"fr": "Contenu de la page",
"en": "Page content"
},
"css": {
"en": "p { color: black; }",
"fr": "p { color: black; }",
}
},
"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 |
template |
The HTML template used by this page |
content page_content object |
The internationalized page content |
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 expandable |
The user who last modified the page |
author user object expandable |
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 |
The page content object
Example object
{
"html": {
"en": "<p>Hello</p>",
"fr": "<p>Bonjour</p>"
},
"css": {
"en": "p { color: black; }",
"fr": "p { color: black; }"
}
}
Attributes
Attribute | Description |
---|---|
html object |
Internationalized HTML content |
css object |
Internationalized CSS content |
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",
"template": "custom.html",
"content": {
"html": {
"fr": "Contenu de la page",
"en": "Page content"
},
"css": {
"en": "p { color: black; }",
"fr": "p { color: black; }",
}
},
"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",
"template": "custom.html",
"content": {
"html": {
"fr": "Contenu de la page",
"en": "Page content"
},
"css": {
"en": "p { color: black; }",
"fr": "p { color: black; }",
}
},
"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", "template": "contact.html", "content": {"html": {"fr": "Contenu de la page", "en": "Page content"}, "css": {"fr": "p { color: black; }", "en": "p { color: black; }"}}, "tags": ["tag1", "tag2"], "restricted": true}'
Example response
{
"slug": "my-page",
"title": {
"fr": "Titre de la page",
"en": "Page title"
},
"description": "The page description",
"template": "contact.html",
"content": {
"html": {
"fr": "Contenu de la page",
"en": "Page content"
},
"css": {
"en": "p { color: black; }",
"fr": "p { color: black; }",
}
},
"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 |
template |
The HTML template used by this page |
content page_content object |
The internationalized page content |
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", "template": "contact.html", "content": {"html": {"fr": "Contenu de la page", "en": "Page content"}, "css": {"fr": "p { color: black; }", "en": "p { color: black; }"}}, "tags": ["tag1", "tag2"], "restricted": true}'
Example response
{
"slug": "my-page",
"title": {
"fr": "Titre de la page",
"en": "Page title"
},
"description": "The page description",
"template": "contact.html",
"content": {
"html": {
"fr": "Contenu de la page",
"en": "Page content"
},
"css": {
"en": "p { color: black; }",
"fr": "p { color: black; }",
}
},
"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 |
template |
The HTML template used by this page |
content page_content object |
The internationalized page content |
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",
"template": "contact.html",
"content": {
"html": {
"fr": "Contenu de la page",
"en": "Page content"
},
"css": {
"en": "p { color: black; }",
"fr": "p { color: black; }",
}
},
"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:
- a page restriction through the
restricted
attribute in the page object, which defines if a page is visible to every user who can explore the portal - specific rulesets for users and groups
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
GET
Retrieve all user level page security rulesetsPOST
Create a new user level page security ruleset
/pages/{PAGE_SLUG}/security/users/{USERNAME}
GET
Retrieve a user level page security rulesetPUT
Update a user level page security rulesetDELETE
Delete a user level page security ruleset
Group level page security ruleset
/pages/{PAGE_SLUG}/security/groups
GET
Retrieve all group level page security rulesetsPOST
Create a new group level page security ruleset
/pages/{PAGE_SLUG}/security/groups/{GROUP_ID}
GET
Retrieve a group level page security rulesetPUT
Update a group level page security rulesetDELETE
Delete a group level security ruleset
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 expandable |
The page targeted by this ruleset |
user user object expandable |
The user targeted by this ruleset. Only available for user-level rulesets |
group group object expandable |
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 expandable |
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 expandable |
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:
- datalist
- dateinput
- datetimeinput
- multidatalist
- multiselect
- multitextinput
- richtextinput
- select
- tags
- textinput
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 |