{"id":29035913,"url":"https://github.com/afeld/sodapy","last_synced_at":"2025-06-26T12:36:22.564Z","repository":{"id":27737889,"uuid":"31225609","full_name":"afeld/sodapy","owner":"afeld","description":"Python client for the Socrata Open Data API","archived":false,"fork":false,"pushed_at":"2025-05-05T14:05:31.000Z","size":2006,"stargazers_count":409,"open_issues_count":1,"forks_count":113,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-06-25T05:43:02.164Z","etag":null,"topics":["api-wrapper","python-client","socrata","socrata-api","socrata-library","soda"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afeld.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2015-02-23T19:36:08.000Z","updated_at":"2025-06-03T15:52:51.000Z","dependencies_parsed_at":"2025-05-03T21:34:28.035Z","dependency_job_id":null,"html_url":"https://github.com/afeld/sodapy","commit_stats":null,"previous_names":["afeld/sodapy","xmunoz/sodapy"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/afeld/sodapy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afeld%2Fsodapy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afeld%2Fsodapy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afeld%2Fsodapy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afeld%2Fsodapy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afeld","download_url":"https://codeload.github.com/afeld/sodapy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afeld%2Fsodapy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262068834,"owners_count":23253876,"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":["api-wrapper","python-client","socrata","socrata-api","socrata-library","soda"],"created_at":"2025-06-26T12:36:21.851Z","updated_at":"2025-06-26T12:36:22.554Z","avatar_url":"https://github.com/afeld.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI version](https://badge.fury.io/py/sodapy.svg)](http://badge.fury.io/py/sodapy) [![Build Status](https://github.com/afeld/sodapy/actions/workflows/tests.yml/badge.svg)](https://github.com/afeld/sodapy/actions/workflows/tests.yml) [![Code Coverage](https://codecov.io/gh/afeld/sodapy/graph/badge.svg?token=64R1LqdV8I)](https://codecov.io/gh/afeld/sodapy)\n\n# sodapy\n\nsodapy is a python client for the [Socrata Open Data API](https://dev.socrata.com/).\n\n## Installation\n\nYou can install with `pip install sodapy`.\n\nThis package uses [semantic versioning](https://semver.org/).\n\n## Documentation\n\nThe [official Socrata Open Data API docs](http://dev.socrata.com/) provide thorough documentation of the available methods, as well as [other client libraries](https://dev.socrata.com/libraries/). A quick list of eligible domains to use with this API is available via the [Socrata Discovery API](https://socratadiscovery.docs.apiary.io/#reference/0/count-by-domain/count-by-domain?console=1) or [Socrata's Open Data Network](https://www.opendatanetwork.com/).\n\nThis library supports writing directly to datasets with the Socrata Open Data API. For write operations that use data transformations in the Socrata Data Management Experience (the user interface for creating datasets), use the Socrata Data Management API. For more details on when to use SODA vs the Data Management API, see the [Data Management API documentation](https://socratapublishing.docs.apiary.io/#). A Python SDK for the Socrata Data Management API can be found at [socrata-py](https://github.com/socrata/socrata-py).\n\n## Examples\n\nThere are some [Jupyter](https://jupyter.org/) notebooks in the [examples directory](examples) with usage examples of sodapy in action.\n\n## Interface\n\n### Table of Contents\n\n- [client](#client)\n- [`datasets`](#datasetslimit0-offset0)\n- [`get`](#getdataset_identifier-content_typejson-kwargs)\n- [`get_all`](#get_alldataset_identifier-content_typejson-kwargs)\n- [`get_metadata`](#get_metadatadataset_identifier-content_typejson)\n- [`update_metadata`](#update_metadatadataset_identifier-update_fields-content_typejson)\n- [`download_attachments`](#download_attachmentsdataset_identifier-content_typejson-download_dirsodapy_downloads)\n- [`create`](#createname-kwargs)\n- [`publish`](#publishdataset_identifier-content_typejson)\n- [`set_permission`](#set_permissiondataset_identifier-permissionprivate-content_typejson)\n- [`upsert`](#upsertdataset_identifier-payload-content_typejson)\n- [`replace`](#replacedataset_identifier-payload-content_typejson)\n- [`create_non_data_file`](#create_non_data_fileparams-file_obj)\n- [`replace_non_data_file`](#replace_non_data_filedataset_identifier-params-file_obj)\n- [`delete`](#deletedataset_identifier-row_idnone-content_typejson)\n- [`close`](#close)\n\n### client\n\nImport the library and set up a connection to get started.\n\n```python\nfrom sodapy import Socrata\nclient = Socrata(\n    \"sandbox.demo.socrata.com\",\n    \"FakeAppToken\",\n    username=\"fakeuser@somedomain.com\",\n    password=\"mypassword\",\n    timeout=10\n)\n```\n\n`username` and `password` are only required for creating or modifying data. An application token isn't strictly required (can be `None`), but queries executed from a client without an application token will be subjected to strict throttling limits. You may want to increase the `timeout` seconds when making large requests. To create a bare-bones client:\n\n```python\nclient = Socrata(\"sandbox.demo.socrata.com\", None)\n```\n\nA client can also be created with a context manager to obviate the need for teardown:\n\n```python\nwith Socrata(\"sandbox.demo.socrata.com\", None) as client:\n    # do some stuff\n```\n\nThe client, by default, makes requests over HTTPS. To modify this behavior, or to make requests through a proxy, take a look [here](https://github.com/afeld/sodapy/issues/31#issuecomment-302176628).\n\n### datasets(limit=0, offset=0)\n\nRetrieve datasets associated with a particular domain. The optional `limit` and `offset` keyword args can be used to retrieve a subset of the datasets. By default, all datasets are returned.\n\n    \u003e\u003e\u003e client.datasets()\n    [{\"resource\" : {\"name\" : \"Approved Building Permits\", \"id\" : \"msk6-43c6\", \"parent_fxf\" : null, \"description\" : \"Data of approved building/construction permits\",...}, {resource : {...}}, ...]\n\n### get(dataset_identifier, content_type=\"json\", \\*\\*kwargs)\n\nRetrieve data from the requested resources. Filter and query data by field name, id, or using [SoQL keywords](https://dev.socrata.com/docs/queries/).\n\n    \u003e\u003e\u003e client.get(\"nimj-3ivp\", limit=2)\n    [{u'geolocation': {u'latitude': u'41.1085', u'needs_recoding': False, u'longitude': u'-117.6135'}, u'version': u'9', u'source': u'nn', u'region': u'Nevada', u'occurred_at': u'2012-09-14T22:38:01', u'number_of_stations': u'15', u'depth': u'7.60', u'magnitude': u'2.7', u'earthquake_id': u'00388610'}, {...}]\n\n    \u003e\u003e\u003e client.get(\"nimj-3ivp\", where=\"depth \u003e 300\", order=\"magnitude DESC\", exclude_system_fields=False)\n    [{u'geolocation': {u'latitude': u'-15.563', u'needs_recoding': False, u'longitude': u'-175.6104'}, u'version': u'9', u':updated_at': 1348778988, u'number_of_stations': u'275', u'region': u'Tonga', u':created_meta': u'21484', u'occurred_at': u'2012-09-13T21:16:43', u':id': 132, u'source': u'us', u'depth': u'328.30', u'magnitude': u'4.8', u':meta': u'{\\n}', u':updated_meta': u'21484', u'earthquake_id': u'c000cnb5', u':created_at': 1348778988}, {...}]\n\n    \u003e\u003e\u003e client.get(\"nimj-3ivp/193\", exclude_system_fields=False)\n    {u'geolocation': {u'latitude': u'21.6711', u'needs_recoding': False, u'longitude': u'142.9236'}, u'version': u'C', u':updated_at': 1348778988, u'number_of_stations': u'136', u'region': u'Mariana Islands region', u':created_meta': u'21484', u'occurred_at': u'2012-09-13T11:19:07', u':id': 193, u'source': u'us', u'depth': u'300.70', u'magnitude': u'4.4', u':meta': u'{\\n}', u':updated_meta': u'21484', u':position': 193, u'earthquake_id': u'c000cmsq', u':created_at': 1348778988}\n\n    \u003e\u003e\u003e client.get(\"nimj-3ivp\", region=\"Kansas\")\n    [{u'geolocation': {u'latitude': u'38.10', u'needs_recoding': False, u'longitude': u'-100.6135'}, u'version': u'9', u'source': u'nn', u'region': u'Kansas', u'occurred_at': u'2010-09-19T20:52:09', u'number_of_stations': u'15', u'depth': u'300.0', u'magnitude': u'1.9', u'earthquake_id': u'00189621'}, {...}]\n\n### get_all(dataset_identifier, content_type=\"json\", \\*\\*kwargs)\n\nRead data from the requested resource, paginating over all results. Accepts the same arguments as [`get()`](#getdataset_identifier-content_typejson-kwargs). Returns a generator.\n\n    \u003e\u003e\u003e client.get_all(\"nimj-3ivp\")\n    \u003cgenerator object Socrata.get_all at 0x7fa0dc8be7b0\u003e\n\n    \u003e\u003e\u003e for item in client.get_all(\"nimj-3ivp\"):\n    ...     print(item)\n    ...\n    {'geolocation': {'latitude': '-15.563', 'needs_recoding': False, 'longitude': '-175.6104'}, 'version': '9', ':updated_at': 1348778988, 'number_of_stations': '275', 'region': 'Tonga', ':created_meta': '21484', 'occurred_at': '2012-09-13T21:16:43', ':id': 132, 'source': 'us', 'depth': '328.30', 'magnitude': '4.8', ':meta': '{\\n}', ':updated_meta': '21484', 'earthquake_id': 'c000cnb5', ':created_at': 1348778988}\n    ...\n\n    \u003e\u003e\u003e import itertools\n    \u003e\u003e\u003e items = client.get_all(\"nimj-3ivp\")\n    \u003e\u003e\u003e first_five = list(itertools.islice(items, 5))\n    \u003e\u003e\u003e len(first_five)\n    5\n\n### get_metadata(dataset_identifier, content_type=\"json\")\n\nRetrieve the metadata associated with a particular dataset.\n\n    \u003e\u003e\u003e client.get_metadata(\"nimj-3ivp\")\n    {\"newBackend\": false, \"licenseId\": \"CC0_10\", \"publicationDate\": 1436655117, \"viewLastModified\": 1451289003, \"owner\": {\"roleName\": \"administrator\", \"rights\": [], \"displayName\": \"Brett\", \"id\": \"cdqe-xcn5\", \"screenName\": \"Brett\"}, \"query\": {}, \"id\": \"songs\", \"createdAt\": 1398014181, \"category\": \"Public Safety\", \"publicationAppendEnabled\": true, \"publicationStage\": \"published\", \"rowsUpdatedBy\": \"cdqe-xcn5\", \"publicationGroup\": 1552205, \"displayType\": \"table\", \"state\": \"normal\", \"attributionLink\": \"http://foo.bar.com\", \"tableId\": 3523378, \"columns\": [], \"metadata\": {\"rdfSubject\": \"0\", \"renderTypeConfig\": {\"visible\": {\"table\": true}}, \"availableDisplayTypes\": [\"table\", \"fatrow\", \"page\"], \"attachments\": ... }}\n\n### update_metadata(dataset_identifier, update_fields, content_type=\"json\")\n\nUpdate the metadata for a particular dataset. `update_fields` should be a dictionary containing only the metadata keys that you wish to overwrite.\n\nNote: Invalid payloads to this method could corrupt the dataset or visualization. See [this comment](https://github.com/afeld/sodapy/issues/22#issuecomment-249971379) for more information.\n\n    \u003e\u003e\u003e client.update_metadata(\"nimj-3ivp\", {\"attributionLink\": \"https://anothertest.com\"})\n    {\"newBackend\": false, \"licenseId\": \"CC0_10\", \"publicationDate\": 1436655117, \"viewLastModified\": 1451289003, \"owner\": {\"roleName\": \"administrator\", \"rights\": [], \"displayName\": \"Brett\", \"id\": \"cdqe-xcn5\", \"screenName\": \"Brett\"}, \"query\": {}, \"id\": \"songs\", \"createdAt\": 1398014181, \"category\": \"Public Safety\", \"publicationAppendEnabled\": true, \"publicationStage\": \"published\", \"rowsUpdatedBy\": \"cdqe-xcn5\", \"publicationGroup\": 1552205, \"displayType\": \"table\", \"state\": \"normal\", \"attributionLink\": \"https://anothertest.com\", \"tableId\": 3523378, \"columns\": [], \"metadata\": {\"rdfSubject\": \"0\", \"renderTypeConfig\": {\"visible\": {\"table\": true}}, \"availableDisplayTypes\": [\"table\", \"fatrow\", \"page\"], \"attachments\": ... }}\n\n### download_attachments(dataset_identifier, content_type=\"json\", download_dir=\"~/sodapy_downloads\")\n\nDownload all attachments associated with a dataset. Return a list of paths to the downloaded files.\n\n    \u003e\u003e\u003e client.download_attachments(\"nimj-3ivp\", download_dir=\"~/Desktop\")\n        ['/Users/xmunoz/Desktop/nimj-3ivp/FireIncident_Codes.PDF', '/Users/xmunoz/Desktop/nimj-3ivp/AccidentReport.jpg']\n\n### create(name, \\*\\*kwargs)\n\nCreate a new dataset. Optionally, specify keyword args such as:\n\n- `description` description of the dataset\n- `columns` list of fields\n- `category` dataset category (must exist in /admin/metadata)\n- `tags` list of tag strings\n- `row_identifier` field name of primary key\n- `new_backend` whether to create the dataset in the new backend\n\nExample usage:\n\n    \u003e\u003e\u003e columns = [{\"fieldName\": \"delegation\", \"name\": \"Delegation\", \"dataTypeName\": \"text\"}, {\"fieldName\": \"members\", \"name\": \"Members\", \"dataTypeName\": \"number\"}]\n    \u003e\u003e\u003e tags = [\"politics\", \"geography\"]\n    \u003e\u003e\u003e client.create(\"Delegates\", description=\"List of delegates\", columns=columns, row_identifier=\"delegation\", tags=tags, category=\"Transparency\")\n    {u'id': u'2frc-hyvj', u'name': u'Foo Bar', u'description': u'test dataset', u'publicationStage': u'unpublished', u'columns': [ { u'name': u'Foo', u'dataTypeName': u'text', u'fieldName': u'foo', ... }, { u'name': u'Bar', u'dataTypeName': u'number', u'fieldName': u'bar', ... } ], u'metadata': { u'rowIdentifier': 230641051 }, ... }\n\n### publish(dataset_identifier, content_type=\"json\")\n\nPublish a dataset after creating it, i.e. take it out of 'working copy' mode. The dataset id `id` returned from `create` will be used to publish.\n\n    \u003e\u003e\u003e client.publish(\"2frc-hyvj\")\n    {u'id': u'2frc-hyvj', u'name': u'Foo Bar', u'description': u'test dataset', u'publicationStage': u'unpublished', u'columns': [ { u'name': u'Foo', u'dataTypeName': u'text', u'fieldName': u'foo', ... }, { u'name': u'Bar', u'dataTypeName': u'number', u'fieldName': u'bar', ... } ], u'metadata': { u'rowIdentifier': 230641051 }, ... }\n\n### set_permission(dataset_identifier, permission=\"private\", content_type=\"json\")\n\nSet the permissions of a dataset to public or private.\n\n    \u003e\u003e\u003e client.set_permission(\"2frc-hyvj\", \"public\")\n    \u003cResponse [200]\u003e\n\n### upsert(dataset_identifier, payload, content_type=\"json\")\n\nCreate a new row in an existing dataset.\n\n    \u003e\u003e\u003e data = [{'Delegation': 'AJU', 'Name': 'Alaska', 'Key': 'AL', 'Entity': 'Juneau'}]\n    \u003e\u003e\u003e client.upsert(\"eb9n-hr43\", data)\n    {u'Errors': 0, u'Rows Deleted': 0, u'Rows Updated': 0, u'By SID': 0, u'Rows Created': 1, u'By RowIdentifier': 0}\n\nUpdate/Delete rows in a dataset.\n\n    \u003e\u003e\u003e data = [{'Delegation': 'sfa', ':id': 8, 'Name': 'bar', 'Key': 'doo', 'Entity': 'dsfsd'}, {':id': 7, ':deleted': True}]\n    \u003e\u003e\u003e client.upsert(\"eb9n-hr43\", data)\n    {u'Errors': 0, u'Rows Deleted': 1, u'Rows Updated': 1, u'By SID': 2, u'Rows Created': 0, u'By RowIdentifier': 0}\n\n`upsert`'s can even be performed with a csv file.\n\n    \u003e\u003e\u003e data = open(\"upsert_test.csv\")\n    \u003e\u003e\u003e client.upsert(\"eb9n-hr43\", data)\n    {u'Errors': 0, u'Rows Deleted': 0, u'Rows Updated': 1, u'By SID': 1, u'Rows Created': 0, u'By RowIdentifier': 0}\n\n### replace(dataset_identifier, payload, content_type=\"json\")\n\nSimilar in usage to `upsert`, but overwrites existing data.\n\n    \u003e\u003e\u003e data = open(\"replace_test.csv\")\n    \u003e\u003e\u003e client.replace(\"eb9n-hr43\", data)\n    {u'Errors': 0, u'Rows Deleted': 0, u'Rows Updated': 0, u'By SID': 0, u'Rows Created': 12, u'By RowIdentifier': 0}\n\n### create_non_data_file(params, file_obj)\n\nCreates a new file-based dataset with the name provided in the files\ntuple. A valid file input would be:\n\n```python\nfiles = (\n    {'file': (\"gtfs2\", open('myfile.zip', 'rb'))}\n)\n```\n\n```python\nwith open(nondatafile_path, 'rb') as f:\n    files = (\n        {'file': (\"nondatafile.zip\", f)}\n    )\n    response = client.create_non_data_file(params, files)\n```\n\n### replace_non_data_file(dataset_identifier, params, file_obj)\n\nSame as create_non_data_file, but replaces a file that already exists in a\nfile-based dataset.\n\nNote: a table-based dataset cannot be replaced by a file-based dataset. Use create_non_data_file in order to replace.\n\n```python\nwith open(nondatafile_path, 'rb') as f:\n    files = (\n        {'file': (\"nondatafile.zip\", f)}\n    )\nresponse = client.replace_non_data_file(DATASET_IDENTIFIER, {}, files)\n```\n\n### delete(dataset_identifier, row_id=None, content_type=\"json\")\n\nDelete an individual row.\n\n    \u003e\u003e\u003e client.delete(\"nimj-3ivp\", row_id=2)\n    \u003cResponse [200]\u003e\n\nDelete the entire dataset.\n\n    \u003e\u003e\u003e client.delete(\"nimj-3ivp\")\n    \u003cResponse [200]\u003e\n\n### close()\n\nClose the session when you're finished.\n\n```python\nclient.close()\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## History\n\nThis package was initially created and maintained by [**@xmunoz**](https://github.com/xmunoz). On March 8, 2025, ownership was transferred to [**@afeld**](https://github.com/afeld).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafeld%2Fsodapy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafeld%2Fsodapy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafeld%2Fsodapy/lists"}