Skip to content

Updated README with more detailed usage examples and more explanation… #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DynataRidley merged 3 commits into from
Jan 14, 2020
Merged

Updated README with more detailed usage examples and more explanation… #38

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fb8b33c
Updated README with more detailed usage examples and more explanation…
RidleyLarsen Jan 14, 2020
fc2f6f9
Removed whitespace from python code example. Added links to API docs …
RidleyLarsen Jan 14, 2020
d2c01ea
version badge
dynata-bradley Jan 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 69 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,108 @@
# python-demandapi-client

[![PyPI version](https://badge.fury.io/py/dynatademand.svg)](https://pypi.org/project/dynatademand/)

<a href="https://github.com/dynata/python-demandapi-client/actions?query=branch%3Adev"><img alt="GitHub Actions status" src="https://github.com/dynata/python-demandapi-client/workflows/python-tests/badge.svg"></a>

A Python client library for the [Dynata Demand API](https://developers.dynata.com/). There are also [go](https://github.com/researchnow/go-samplifyapi-client) and [.NET](https://github.com/researchnow/dotnet-samplifyapi-client) clients available.

## Setup

The client requires environment variables to be set for the Dynata Demand API credentials. These can be found in `.env-example`.
You can install the Demand API client with:

pip install dynatademand

You can provide your Demand API credentials in a couple of ways. They can be set in the environment (a sample config is provided in `.env-example`) or you can provide them while creating the client object.

## Example Usage

demandapi = DemandAPIClient()
demandapi.authenticate()
demandapi.logout()
```python
# You can optionally provide your credentials here instead of environment variables.
demandapi = DemandAPIClient("client_id", "username", "password")
demandapi.authenticate()

# Any function requiring one or more IDs should be provided as positional arguments.
demandapi.get_project(7)

# Provide query parameters as keyword-arguments.
demandapi.get_projects(state="LAUNCHED")

# Functions that send data in a request body accept a python dictionary.
# Your data will be validated against the schemas provided in the Demand API documentation.
project_data = {
'title': 'My New Survey',
...
}
demandapi.create_project(project_data)
```

## Supported API Functions

Links to the Demand API documentation are included for each function.

### Authentication Functions

authenticate()
refresh_access_token()
logout()
[Obtain Access Token](https://developers.dynata.com/demand-api-reference/authentication/authentication/post-token): authenticate()
[Refresh Access Token](https://developers.dynata.com/demand-api-reference/authentication/authentication/post-token-refresh): refresh_access_token()
[Logout](https://developers.dynata.com/demand-api-reference/authentication/authentication/post-logout): logout()

### Event Functions

get_event(event_id)
get_events(\*\*kwargs)
[Get Event](https://developers.dynata.com/demand-api-reference/notifications/events/get-event): get_event(event_id)
[Get Events](https://developers.dynata.com/demand-api-reference/notifications/events/get-events): get_events(\*\*kwargs)

### Project Functions

buy_project(project_id, buy_data)
close_project(project_id)
create_project(project_data)
get_project(project_id)
get_projects(\*\*kwargs)
reconcile_project(project_id, reconcile_data)
update_project(project_id, update_data)
get_project_detailed_report(project_id)
get_feasibility(project_id)
get_invoice(project_id)
[Buy Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-project-buy): buy_project(project_id, buy_data)
[Close Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-close-project): close_project(project_id)
[Create Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-projects): create_project(project_data)
[Get Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/get-project): get_project(project_id)
[Get Projects](https://developers.dynata.com/demand-api-reference/core-resources/projects/get-projects): get_projects(\*\*kwargs)
[Update Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-project): update_project(project_id, update_data)
[Get Project Detailed Report](https://developers.dynata.com/demand-api-reference/core-resources/projects/get-project-detailed-report): get_project_detailed_report(project_id)
[Get Pricing & Feasibility](https://developers.dynata.com/demand-api-reference/core-resources/pricing-feasibility/get-pricing-feasibility): get_feasibility(project_id)
[Get Invoice PDF](https://developers.dynata.com/demand-api-reference/billing_invoicing/invoicing/get-invoices): get_invoice(project_id)

### Line Item Functions

add_line_item(project_id, lineitem_data)
close_line_item(project_id, line_item_id)
get_line_item(project_id, line_item_id)
get_line_items(project_id, \*\*kwargs)
launch_line_item(project_id, line_item_id)
pause_line_item(project_id, line_item_id)
update_line_item(project_id, line_item_id, line_item_data)
get_line_item_detailed_report(project_id, line_item_id)
[Add Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitems): add_line_item(project_id, lineitem_data)
[Close Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem-close): close_line_item(project_id, line_item_id)
[Get Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/get-lineitem): get_line_item(project_id, line_item_id)
[Get Line Items](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/get-lineitems): get_line_items(project_id, \*\*kwargs)
[Launch Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem-launch): launch_line_item(project_id, line_item_id)
[Pause Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem-pause): pause_line_item(project_id, line_item_id)
[Update Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem): update_line_item(project_id, line_item_id, line_item_data)
[Get Line Item Detailed Report](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/get-detailed-line-item): get_line_item_detailed_report(project_id, line_item_id)

### Misc Functions

get_attributes(country_code, language_code, \*\*kwargs)
get_countries(\*\*kwargs)
get_sources()
get_survey_topics(\*\*kwargs)
[Get Attributes](https://developers.dynata.com/demand-api-reference/data_endpoints/attributes/get-attributes): get_attributes(country_code, language_code, \*\*kwargs)
[Get Countries](https://developers.dynata.com/demand-api-reference/data_endpoints/countries-languages/get-countries): get_countries(\*\*kwargs)
[Get Sources](https://developers.dynata.com/demand-api-reference/data_endpoints/supplier-sources/get-sources): get_sources()
[Get Survey Topics](https://developers.dynata.com/demand-api-reference/data_endpoints/categories/get-survey-topic): get_survey_topics(\*\*kwargs)

## Contributing

Information on [contributing](CONTRIBUTING.md).

## Testing

To run the tests,
To run the tests, you will need to install the development requirements to your environment. It's recommended to create a virtual environment for your installation to avoid any package conflicts.

You can check out the code by running:

git clone https://github.com/dynata/python-demandapi-client.git
cd python-demandapi-client

And you can create an environment by running:

# If you're using Python 2.7
virtualenv venv
. venv/bin/activate

# Or if you're using Python 3:
python3 -m venv venv

source venv/bin/activate
pip install -r requirements.txt
pytest tests
deactivate

to run the tests for this project.
While your virtual environment is activated, you can run `pytest tests` to run the tests.