Integrations

API Client Methods

The following functions are all methods of the datadotworld.api_client() class

add_files_via_url(dataset_key, files={})

Add or update dataset files linked to source URLs

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • files (dict) – Dict containing the name of files and metadata Uses file name as a dict containing File description, labels and source URLs to add or update (Default value = {}) description and labels are optional.

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> url='http://www.acme.inc/example.csv'>>> api_client=dw.api_client()>>> api_client.add_files_via_url(... 'username/test-dataset',... {'example.csv':{... 'url':url,... 'labels':['raw data'],... 'description':'file description'}})
add_linked_dataset(project_key, dataset_key)

Link project to an existing dataset

This method links a dataset to project

Parameters
  • project_key (str) – Project identifier, in the form of owner/id

  • dataset_key – Dataset identifier, in the form of owner/id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> linked_dataset=api_client.add_linked_dataset(... 'username/test-project',... 'username/test-dataset')
append_records(dataset_key, stream_id, body)

Append records to a stream.

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • stream_id (str) – Stream unique identifier.

  • body (obj) – Object body

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.append_records('username/test-dataset','streamId',... {'content':'content'})
create_dataset(owner_id, **kwargs)

Create a new dataset

Parameters
  • owner_id (str) – Username of the owner of the new dataset

  • title (str) – Dataset title (will be used to generate dataset id on creation)

  • description (str, optional) – Dataset description

  • summary (str, optional) – Dataset summary markdown

  • tags (list, optional) – Dataset tags

  • license ({'Public Domain', 'PDDL', 'CC-0', 'CC-BY', 'ODC-BY', 'CC-BY-SA', 'ODC-ODbL', 'CC BY-NC', 'CC BY-NC-SA', 'Other'}) – Dataset license

  • visibility ({'OPEN', 'PRIVATE'}) – Dataset visibility

  • files (dict, optional Description and labels are optional) – File name as dict, source URLs, description and labels() as properties

Returns

Newly created dataset key

Return type

str

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> url='http://www.acme.inc/example.csv'>>> api_client.create_dataset(... 'username',title='Test dataset',visibility='PRIVATE',... license='Public Domain',... files={'dataset.csv':{'url':url}})
create_insight(project_key, **kwargs)

Create a new insight

Parameters
  • project_key (str) – Project identifier, in the form of

  • title (str) – Insight title

  • description (str, optional) – Insight description.

  • image_url (str) – If image-based, the URL of the image

  • embed_url (str) – If embed-based, the embeddable URL

  • source_link (str, optional) – Permalink to source code or platform this insight was generated with. Allows others to replicate the steps originally used to produce the insight.

  • data_source_links (array) – One or more permalinks to the data sources used to generate this insight. Allows others to access the data originally used to produce the insight.

Returns

Insight with message and uri object

Return type

object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.create_insight(... 'projectOwner/projectid',title='Test insight',... image_url='url')
create_project(owner_id, **kwargs)

Create a new project

Parameters
  • owner_id (str) – Username of the creator of a project.

  • title (str) – Project title (will be used to generate project id on creation)

  • objective (str, optional) – Short project objective.

  • summary (str, optional) – Long-form project summary.

  • tags (list, optional) – Project tags. Letters numbers and spaces

  • license ({'Public Domain', 'PDDL', 'CC-0', 'CC-BY', 'ODC-BY', 'CC-BY-SA', 'ODC-ODbL', 'CC BY-NC', 'CC BY-NC-SA', 'Other'}) – Project license

  • visibility ({'OPEN', 'PRIVATE'}) – Project visibility

  • files (dict, optional Description and labels are optional) – File name as dict, source URLs, description and labels() as properties

  • linked_datasets (list of object, optional) – Initial set of linked datasets.

Returns

Newly created project key

Return type

str

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.create_project(... 'username',title='project testing',... visibility='PRIVATE',... linked_datasets=[{'owner':'someuser',... 'id':'somedataset'}])
delete_dataset(dataset_key)

Deletes a dataset and all associated data

Parameters

dataset_key (str) – Dataset identifier, in the form of owner/id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.delete_dataset(... 'username/dataset')
delete_files(dataset_key, names)

Delete dataset file(s)

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • names (list of str) – The list of names for files to be deleted

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.delete_files(... 'username/test-dataset',['example.csv'])
delete_insight(project_key, insight_id)

Delete an existing insight.

Parameters
  • project_key (str) – Project identifier, in the form of projectOwner/projectId

  • insight_id (str) – Insight unique id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> del_insight=api_client.delete_insight(... 'username/project','insightid')
delete_project(project_key)

Deletes a project and all associated data

Parameters

project_key (str) – Project identifier, in the form of owner/id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.delete_project(... 'username/test-project')
download_datapackage(dataset_key, dest_dir)

Download and unzip a dataset’s datapackage

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • dest_dir (str or path) – Directory under which datapackage should be saved

Returns

Location of the datapackage descriptor (datapackage.json) in the local filesystem

Return type

path

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> datapackage_descriptor=api_client.download_datapackage(... 'jonloyens/an-intro-to-dataworld-dataset',... '/tmp/test')>>> datapackage_descriptor'/tmp/test/datapackage.json'
download_dataset(dataset_key)

Return a .zip containing all files within the dataset as uploaded.

Parameters

dataset_key (str) – Dataset identifier, in the form of owner/id

Returns

.zip file contain files within dataset

Return type

file object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.download_dataset(... 'username/test-dataset')
download_file(dataset_key, file)

Return a file within the dataset as uploaded.

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • file (str) – File path to be returned

Returns

file in which the data was uploaded

Return type

file object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.download_file('username/test-dataset',... '/my/local/example.csv')
fetch_contributing_datasets(**kwargs)

Fetch datasets that the authenticated user has access to

Parameters
  • limit (str, optional) – Maximum number of items to include in a page of results

  • next (str, optional) – Token from previous result page (to be used when requesting a subsequent page)

  • sort (str, optional) – Property name to sort

Returns

Authenticated user dataset

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> user_dataset=... api_client.fetch_contributing_datasets(){'count': 0, 'records': [], 'next_page_token': None}
fetch_contributing_projects(**kwargs)

Fetch projects that the currently authenticated user has access to

Returns

Authenticated user projects

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> user_projects=... api_client.fetch_contributing_projects(){'count': 0, 'records': [], 'next_page_token': None}
fetch_datasets(**kwargs)

Fetch authenticated user owned datasets

Parameters
  • limit (str, optional) – Maximum number of items to include in a page of results

  • next (str, optional) – Token from previous result page (to be used when requesting a subsequent page)

  • sort (str, optional) – Property name to sort

Returns

Dataset definition, with all attributes

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> user_owned_dataset=api_client.fetch_datasets()
fetch_liked_datasets(**kwargs)

Fetch datasets that authenticated user likes

Parameters
  • limit (str, optional) – Maximum number of items to include in a page of results

  • next (str, optional) – Token from previous result page (to be used when requesting a subsequent page)

  • sort (str, optional) – Property name to sort

Returns

Dataset definition, with all attributes

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> user_liked_dataset=... api_client.fetch_liked_datasets()
fetch_liked_projects(**kwargs)

Fetch projects that the currently authenticated user likes

Returns

Authenticated user projects

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> user_liked_projects=... api_client.fetch_liked_projects()
fetch_projects(**kwargs)

Fetch projects that the currently authenticated user owns

Returns

Authenticated user projects

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> user_projects=... api_client.fetch_projects()
get_dataset(dataset_key)

Retrieve an existing dataset definition

This method retrieves metadata about an existing

Parameters

dataset_key (str) – Dataset identifier, in the form of owner/id

Returns

Dataset definition, with all attributes

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> intro_dataset=api_client.get_dataset(... 'jonloyens/an-intro-to-dataworld-dataset')>>> intro_dataset['title']'An Intro to data.world Dataset'
get_insight(project_key, insight_id, **kwargs)

Retrieve an insight

Parameters
  • project_key (str) – Project identifier, in the form of projectOwner/projectid

  • insight_id (str) – Insight unique identifier.

Returns

Insight definition, with all attributes

Return type

object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> insight=api_client.get_insight(... 'jonloyens/'... 'an-example-project-that-shows-what-to-put-in-data-world',... 'c2538b0c-c200-474c-9631-5ff4f13026eb')>>> insight['title']'Coast Guard Lives Saved by Fiscal Year'
get_insights_for_project(project_key, **kwargs)

Get insights for a project.

Parameters

project_key (str) – Project identifier, in the form of projectOwner/projectid

Returns

Insight results

Return type

object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> insights=api_client.get_insights_for_project(... 'jonloyens/'... 'an-example-project-that-shows-what-to-put-in-data-world'... )
get_project(project_key)

Retrieve an existing project

This method retrieves metadata about an existing project

Parameters

project_key (str) – Project identifier, in the form of owner/id

Returns

Project definition, with all attributes

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> intro_project=api_client.get_project(... 'jonloyens/'... 'an-example-project-that-shows-what-to-put-in-data-world'... )>>> intro_project['title']'An Example Project that Shows What To Put in data.world'
get_user_data()

Retrieve data for authenticated user

Returns

User data, with all attributes

Return type

dict

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> user_data=api_client.get_user_data()>>> user_data[display_name]'Name User'
remove_linked_dataset(project_key, dataset_key)

Unlink dataset

This method unlinks a dataset from a project

Parameters
  • project_key (str) – Project identifier, in the form of owner/id

  • dataset_key – Dataset identifier, in the form of owner/id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.remove_linked_dataset(... 'username/test-project',... 'username/test-dataset')
replace_dataset(dataset_key, **kwargs)

Replace an existing dataset

This method will completely overwrite an existing dataset.

Parameters
  • description (str, optional) – Dataset description

  • summary (str, optional) – Dataset summary markdown

  • tags (list, optional) – Dataset tags

  • license ({'Public Domain', 'PDDL', 'CC-0', 'CC-BY', 'ODC-BY', 'CC-BY-SA', 'ODC-ODbL', 'CC BY-NC', 'CC BY-NC-SA', 'Other'}) – Dataset license

  • visibility ({'OPEN', 'PRIVATE'}) – Dataset visibility

  • files (dict, optional) – File names and source URLs to add or update

  • dataset_key (str) – Dataset identifier, in the form of owner/id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.replace_dataset(... 'username/test-dataset',... visibility='PRIVATE',license='Public Domain',... description='A better description')
replace_insight(project_key, insight_id, **kwargs)

Replace an insight.

Parameters
  • project_key (str) – Projrct identifier, in the form of projectOwner/projectid

  • insight_id (str) – Insight unique identifier.

  • title (str) – Insight title

  • description (str, optional) – Insight description.

  • image_url (str) – If image-based, the URL of the image

  • embed_url (str) – If embed-based, the embeddable URL

  • source_link (str, optional) – Permalink to source code or platform this insight was generated with. Allows others to replicate the steps originally used to produce the insight.

  • data_source_links (array) – One or more permalinks to the data sources used to generate this insight. Allows others to access the data originally used to produce the insight.

Returns

message object

Return type

object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.replace_insight(... 'projectOwner/projectid',... '1230-9324-3424242442',... embed_url='url',... title='Test insight')
replace_project(project_key, **kwargs)

Replace an existing Project

Create a project with a given id or completely rewrite the project, including any previously added files or linked datasets, if one already exists with the given id.

Parameters
  • project_key (str) – Username and unique identifier of the creator of a project in the form of owner/id.

  • title (str) – Project title

  • objective (str, optional) – Short project objective.

  • summary (str, optional) – Long-form project summary.

  • tags (list, optional) – Project tags. Letters numbers and spaces

  • license ({'Public Domain', 'PDDL', 'CC-0', 'CC-BY', 'ODC-BY', 'CC-BY-SA', 'ODC-ODbL', 'CC BY-NC', 'CC BY-NC-SA', 'Other'}) – Project license

  • visibility ({'OPEN', 'PRIVATE'}) – Project visibility

  • files (dict, optional Description and labels are optional) – File name as dict, source URLs, description and labels() as properties

  • linked_datasets (list of object, optional) – Initial set of linked datasets.

Returns

project object

Return type

object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.replace_project(... 'username/test-project',... visibility='PRIVATE',... objective='A better objective',... title='Replace project')
sparql(dataset_key, query, desired_mimetype='application/sparql-results+json', **kwargs)

Executes SPARQL queries against a dataset via POST

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • query (str) – SPARQL query

Returns

file object that can be used in file parsers and data handling modules.

Return type

file object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.sparql_post('username/test-dataset',... query)
sql(dataset_key, query, desired_mimetype='application/json', **kwargs)

Executes SQL queries against a dataset via POST

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • query (str) – SQL query

  • include_table_schema (bool) – Flags indicating to include table schema in the response

Returns

file object that can be used in file parsers and data handling modules.

Return type

file-like object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.sql('username/test-dataset','query')
sync_files(dataset_key)

Trigger synchronization process to update all dataset files linked to source URLs.

Parameters

dataset_key (str) – Dataset identifier, in the form of owner/id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.sync_files('username/test-dataset')
update_dataset(dataset_key, **kwargs)

Update an existing dataset

Parameters
  • description (str, optional) – Dataset description

  • summary (str, optional) – Dataset summary markdown

  • tags (list, optional) – Dataset tags

  • license ({'Public Domain', 'PDDL', 'CC-0', 'CC-BY', 'ODC-BY', 'CC-BY-SA', 'ODC-ODbL', 'CC BY-NC', 'CC BY-NC-SA', 'Other'}) – Dataset license

  • visibility ({'OPEN', 'PRIVATE'}, optional) – Dataset visibility

  • files (dict, optional) – File names and source URLs to add or update

  • dataset_key (str) – Dataset identifier, in the form of owner/id

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.update_dataset(... 'username/test-dataset',... tags=['demo','datadotworld'])
update_insight(project_key, insight_id, **kwargs)

Update an insight.

Note that only elements included in the request will be updated. All omitted elements will remain untouched.

Parameters
  • project_key (str) – Projrct identifier, in the form of projectOwner/projectid

  • insight_id (str) – Insight unique identifier.

  • title (str) – Insight title

  • description (str, optional) – Insight description.

  • image_url (str) – If image-based, the URL of the image

  • embed_url (str) – If embed-based, the embeddable URL

  • source_link (str, optional) – Permalink to source code or platform this insight was generated with. Allows others to replicate the steps originally used to produce the insight.

  • data_source_links (array) – One or more permalinks to the data sources used to generate this insight. Allows others to access the data originally used to produce the insight.

Returns

message object

Return type

object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.update_insight(... 'username/test-project','insightid'... title='demo atadotworld'})
update_project(project_key, **kwargs)

Update an existing project

Parameters
  • project_key (str) – Username and unique identifier of the creator of a project in the form of owner/id.

  • title (str) – Project title

  • objective (str, optional) – Short project objective.

  • summary (str, optional) – Long-form project summary.

  • tags (list, optional) – Project tags. Letters numbers and spaces

  • license ({'Public Domain', 'PDDL', 'CC-0', 'CC-BY', 'ODC-BY', 'CC-BY-SA', 'ODC-ODbL', 'CC BY-NC', 'CC BY-NC-SA', 'Other'}) – Project license

  • visibility ({'OPEN', 'PRIVATE'}) – Project visibility

  • files (dict, optional Description and labels are optional) – File name as dict, source URLs, description and labels() as properties

  • linked_datasets (list of object, optional) – Initial set of linked datasets.

Returns

message object

Return type

object

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.update_project(... 'username/test-project',... tags=['demo','datadotworld'])
upload_files(dataset_key, files, files_metadata={}, **kwargs)

Upload one or more dataset files

Parameters
  • dataset_key (str) – Dataset identifier, in the form of owner/id

  • files (list of str) – The list of names/paths for files stored in the local filesystem

  • expand_archives – Boolean value to indicate files should be expanded upon upload

  • files_metadata (dict optional) – Dict containing the name of files and metadata Uses file name as a dict containing File description, labels and source URLs to add or update

Raises

RestApiException – If a server error occurs

Examples

>>> importdatadotworldasdw>>> api_client=dw.api_client()>>> api_client.upload_files(... 'username/test-dataset',... ['/my/local/example.csv'])