{"id":14959520,"url":"https://github.com/streamlit/gsheets-connection","last_synced_at":"2025-04-08T15:07:11.900Z","repository":{"id":158471905,"uuid":"632633187","full_name":"streamlit/gsheets-connection","owner":"streamlit","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-28T16:26:14.000Z","size":12796,"stargazers_count":112,"open_issues_count":8,"forks_count":45,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-10-29T14:27:51.615Z","etag":null,"topics":["google-sheets","streamlit","streamlit-components"],"latest_commit_sha":null,"homepage":"https://st-gsheets.streamlit.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/streamlit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-25T20:15:20.000Z","updated_at":"2024-10-22T21:42:19.000Z","dependencies_parsed_at":"2024-01-29T20:16:33.934Z","dependency_job_id":"d4f06b21-52f2-4abb-aa01-d9e694913ce3","html_url":"https://github.com/streamlit/gsheets-connection","commit_stats":{"total_commits":47,"total_committers":5,"mean_commits":9.4,"dds":0.276595744680851,"last_synced_commit":"cd9a6ba8eb3033096e8f326f77331e337c15cca7"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamlit%2Fgsheets-connection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamlit%2Fgsheets-connection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamlit%2Fgsheets-connection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamlit%2Fgsheets-connection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/streamlit","download_url":"https://codeload.github.com/streamlit/gsheets-connection/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247867361,"owners_count":21009240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-sheets","streamlit","streamlit-components"],"created_at":"2024-09-24T13:19:54.591Z","updated_at":"2025-04-08T15:07:11.879Z","avatar_url":"https://github.com/streamlit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Streamlit GSheetsConnection\n\nConnect to public or private Google Sheets from your Streamlit app. Powered by `st.connection()` and [gspread](https://github.com/burnash/gspread).\n\nGSheets Connection works in two modes:\n\n- in Read Only mode, using publicly shared Spreadsheet URLs (Read Only mode)\n- CRUD operations support mode, with Authentication using Service Account. In order to use Service Account mode you need to enable Google Drive and Google Sheets API in [Google Developers Console](https://console.developers.google.com/).\n  Follow **Initial setup for CRUD mode** section in order to authenticate your Streamlit app first.\n\n[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://st-gsheets.streamlit.app/)\n\n## Install\n\n```sh\npip install st-gsheets-connection\n```\n\n## Minimal example: publicly shared spreadsheet (read-only)\n\n```python\n# example/st_app.py\n\nimport streamlit as st\nfrom streamlit_gsheets import GSheetsConnection\n\nurl = \"https://docs.google.com/spreadsheets/d/1JDy9md2VZPz4JbYtRPJLs81_3jUK47nx6GYQjgU8qNY/edit?usp=sharing\"\n\nconn = st.connection(\"gsheets\", type=GSheetsConnection)\n\ndata = conn.read(spreadsheet=url, usecols=[0, 1])\nst.dataframe(data)\n```\n\n## Service account / CRUD example\n\n### Initial setup for private spreadsheet and/or CRUD mode\n\n1. Setup `.streamlit/secrets.toml` inside your Streamlit app root directory,\n   check out [Secret management documentation](https://docs.streamlit.io/streamlit-community-cloud/get-started/deploy-an-app/connect-to-data-sources/secrets-management) for references.\n2. [Enable API Access for a Project](https://docs.gspread.org/en/v5.7.1/oauth2.html#enable-api-access-for-a-project)\n   - Head to [Google Developers Console](https://console.developers.google.com/) and create a new project (or select the one you already have).\n   - In the box labeled “Search for APIs and Services”, search for “Google Drive API” and enable it.\n   - In the box labeled “Search for APIs and Services”, search for “Google Sheets API” and enable it.\n3. [Using Service Account](https://docs.gspread.org/en/v5.7.1/oauth2.html#for-bots-using-service-account)\n   - Enable API Access for a Project if you haven’t done it yet.\n   - Go to “APIs \u0026 Services \u003e Credentials” and choose “Create credentials \u003e Service account key”.\n   - Fill out the form\n   - Click “Create” and “Done”.\n   - Press “Manage service accounts” above Service Accounts.\n   - Press on ⋮ near recently created service account and select “Manage keys” and then click on “ADD KEY \u003e Create new key”.\n   - Select JSON key type and press “Create”.\n\nYou will automatically download a JSON file with credentials. It may look like this:\n\n```\n{\n    \"type\": \"service_account\",\n    \"project_id\": \"api-project-XXX\",\n    \"private_key_id\": \"2cd … ba4\",\n    \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nNrDyLw … jINQh/9\\n-----END PRIVATE KEY-----\\n\",\n    \"client_email\": \"473000000000-yoursisdifferent@developer.gserviceaccount.com\",\n    \"client_id\": \"473 … hd.apps.googleusercontent.com\",\n    ...\n}\n```\n\nRemember the path to the downloaded credentials file. Also, in the next step you’ll need the value of client_email from this file.\n\n- **:red[Very important!]** Go to your spreadsheet and share it with a client_email from the step above. Just like you do with any other Google account. If you don’t do this, you’ll get a `gspread.exceptions.SpreadsheetNotFound` exception when trying to access this spreadsheet from your application or a script.\n\n4. Inside `streamlit/secrets.toml` place `service_account` configuration from downloaded JSON file, in the following format (where `gsheets` is your `st.connection` name):\n\n```\n# .streamlit/secrets.toml\n\n[connections.gsheets]\nspreadsheet = \"\u003cspreadsheet-name-or-url\u003e\"\nworksheet = \"\u003cworksheet-gid-or-folder-id\u003e\"  # worksheet GID is used when using Public Spreadsheet URL, when usign service_account it will be picked as folder_id\ntype = \"\"  # leave empty when using Public Spreadsheet URL, when using service_account -\u003e type = \"service_account\"\nproject_id = \"\"\nprivate_key_id = \"\"\nprivate_key = \"\"\nclient_email = \"\"\nclient_id = \"\"\nauth_uri = \"\"\ntoken_uri = \"\"\nauth_provider_x509_cert_url = \"\"\nclient_x509_cert_url = \"\"\n```\n\n### Code\n\n```python\n# example/st_app_gsheets_using_service_account.py\n\nimport streamlit as st\nfrom streamlit_gsheets import GSheetsConnection\n\nst.title(\"Read Google Sheet as DataFrame\")\n\nconn = st.connection(\"gsheets\", type=GSheetsConnection)\ndf = conn.read(worksheet=\"Example 1\")\n\nst.dataframe(df)\n```\n\n```toml\n# .streamlit/secrets.toml\n\n[connections.gsheets]\nspreadsheet = \"\u003cspreadsheet-name-or-url\u003e\"\nworksheet = \"\u003cworksheet-gid-or-folder-id\u003e\"  # worksheet GID is used when using Public Spreadsheet URL, when usign service_account it will be picked as folder_id\ntype = \"\"  # leave empty when using Public Spreadsheet URL, when using service_account -\u003e type = \"service_account\"\nproject_id = \"\"\nprivate_key_id = \"\"\nprivate_key = \"\"\nclient_email = \"\"\nclient_id = \"\"\nauth_uri = \"\"\ntoken_uri = \"\"\nauth_provider_x509_cert_url = \"\"\nclient_x509_cert_url = \"\"\n```\n\n```txt\n# requirements.txt\n\nstreamlit==1.22\ngit+https://github.com/streamlit/gsheets-connection\npandasql  # this is for example/st_app.py only\n```\n\n## Full example\n\nCheck gsheets_connection/example directory for full example of the usage.\n\n## Q\u0026A\n\n- \u003e Does this work with a public spreadsheet without the authentication details? Or only a private spreadsheet?\n\n  GSheets Connection works in two modes:\n\n  - in Read Only mode, using publicly shared Spreadsheet URLs (Read Only mode)\n  - CRUD operations support mode, with Authentication using Service Account. In order to use Service Account mode you need to enable Google Drive and Google Sheets API in [Google Developers Console](https://console.developers.google.com/).\n    Follow **Initial setup for CRUD mode** section in order to authenticate your Streamlit app first.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamlit%2Fgsheets-connection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstreamlit%2Fgsheets-connection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamlit%2Fgsheets-connection/lists"}