### Usage Examples - Basic Setup and Context Managers

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Demonstrates the basic setup of the Socrata client and its usage as a context manager.

```python
from sodapy import Socrata

# Using context manager for automatic cleanup
with Socrata("data.cityofnewyork.us", "your_app_token") as client:
    print("Client created and ready.")
    # Perform operations here
    dataset_name = "erm2-nwe9"
    results = client.get(dataset_name, limit=2)
    print(f"Retrieved {len(results)} records from {dataset_name}.")

print("Client connection closed automatically.")
```

--------------------------------

### client

Source: https://github.com/afeld/sodapy/blob/main/README.md

Import the library and set up a connection to get started. Username and password are only required for creating or modifying data. An application token isn't strictly required but queries without one are subject to throttling. A client can be created with a context manager for automatic teardown.

```APIDOC
## client

Import the library and set up a connection to get started.

```python
from sodapy import Socrata
client = Socrata(
    "sandbox.demo.socrata.com",
    "FakeAppToken",
    username="fakeuser@somedomain.com",
    password="mypassword",
    timeout=10
)
```

`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:

```python
client = Socrata("sandbox.demo.socrata.com", None)
```

A client can also be created with a context manager to obviate the need for teardown:

```python
with Socrata("sandbox.demo.socrata.com", None) as client:
    # do some stuff
```

The 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).
```

--------------------------------

### Usage Examples - File-Based Datasets (Create)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of creating a file-based dataset by uploading a file.

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

# Assume 'my_data.csv' is a local CSV file
# with open("my_data.csv", "rb") as f:
#     dataset_info = client.create_dataset("my_data.csv", f, "text/csv")
# print(f"File-based dataset created with ID: {dataset_info['id']}")
```

--------------------------------

### Install sodapy

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/00-START-HERE.txt

Use pip to install the sodapy library.

```bash
pip install sodapy
```

--------------------------------

### Usage Examples - Writing Data (Create)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of creating a new dataset with initial data using the create() method.

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

dataset_metadata = {
    "name": "API Created Dataset",
    "description": "A dataset created via the sodapy library."
}
dataset_schema = {
    "columns": [
        {"name": "id", "dataTypeName": "text"},
        {"name": "value", "dataTypeName": "number"}
    ]
}
data_to_create = [
    {"id": "row1", "value": 10},
    {"id": "row2", "value": 20}
]

# Create dataset and add initial data
created_dataset_info = client.create(dataset_metadata, dataset_schema, data_to_create)
print(f"Dataset created with ID: {created_dataset_info['id']}")
```

--------------------------------

### Usage Examples - Dataset Management (Publish)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of publishing a dataset to make it publicly accessible.

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

# Publish dataset with ID 'dataset_id'
client.publish("dataset_id")
print("Dataset published successfully.")
```

--------------------------------

### Query Data Examples

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/04-endpoints.md

Examples of retrieving data from a dataset using different query parameters and formats. These requests target the data endpoint.

```http
GET /resource/nimj-3ivp.json?$limit=10
```

```http
GET /resource/nimj-3ivp.json?$where=depth > 300&$order=magnitude DESC
```

```http
GET /resource/nimj-3ivp/193.json
```

```http
GET /resource/nimj-3ivp.csv?$select=magnitude,region&$limit=100
```

--------------------------------

### Usage Examples - File-Based Datasets (Replace)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of replacing the content of a file-based dataset by uploading a new file.

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

# Assume 'updated_data.csv' is the new file content
# with open("updated_data.csv", "rb") as f:
#     client.replace_dataset("dataset_id", f, "updated_data.csv", "text/csv")
# print("File-based dataset content replaced.")
```

--------------------------------

### Usage Examples - Reading Data with Aggregations

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to use SoQL aggregations (e.g., COUNT, AVG) to summarize data.

```python
from sodapy import Socrata

client = Socrata("data.cityofnewyork.us", "your_app_token")

dataset_name = "erm2-nwe9"

# Example: Count the number of records by borough
query = "SELECT COUNT(*) as count, borough FROM \"erm2-nwe9\" GROUP BY borough"
results = client.get(dataset_name, query=query)

print("Record counts by borough:")
for row in results:
    print(f"- {row['borough']}: {row['count']}")
```

--------------------------------

### Usage Examples - Writing Data (Replace)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of completely replacing the data in a dataset with new data using replace().

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

data_to_replace = [
    {"id": "rowA", "value": 100},
    {"id": "rowB", "value": 200}
]

# Replace all data in 'dataset_id'
replaced_count = client.replace("dataset_id", data_to_replace)
print(f"Replaced {replaced_count} rows.")
```

--------------------------------

### Usage Examples - Reading Data with Pagination

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Shows how to retrieve data in chunks (pages) to handle large datasets efficiently.

```python
from sodapy import Socrata

client = Socrata("data.cityofnewyork.us", "your_app_token")

dataset_name = "erm2-nwe9"
all_results = []
limit = 1000  # Number of records per page
offset = 0

while True:
    results = client.get(dataset_name, limit=limit, offset=offset)
    if not results:
        break  # No more data
    all_results.extend(results)
    offset += limit
    print(f"Retrieved {len(all_results)} records so far...")

print(f"Total records retrieved: {len(all_results)}")
```

--------------------------------

### Usage Examples - Monitoring and Logging

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Integrating logging to monitor API requests and responses for debugging and performance analysis.

```python
import logging
from sodapy import Socrata

logging.basicConfig(level=logging.DEBUG) # Set to INFO for less verbosity

client = Socrata("data.cityofnewyork.us", "your_app_token")

# The client will now log its requests and responses due to basicConfig
try:
    results = client.get("erm2-nwe9", limit=1)
    print(f"Successfully retrieved {len(results)} record.")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    client.close()
```

--------------------------------

### Configure Logging and Monitor API Performance

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/07-usage-examples.md

Set up basic logging and create a Socrata client. This example also shows how to measure the time taken to retrieve a large dataset. The client logs a warning if no app token is provided.

```python
import logging
from sodapy import Socrata

# Configure logging
logging.basicConfig(level=logging.WARNING)

# Create client (logs warning if no app token)
client = Socrata("domain.com", None)

# Perform operations
results = client.get("dataset_id")

# For detailed monitoring
import time
start = time.time()
results = client.get("large_dataset")
elapsed = time.time() - start
print(f"Retrieved {len(results)} rows in {elapsed:.2f}s")
```

--------------------------------

### Usage Examples - Writing Data (Upsert)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of updating existing records or inserting new ones using the upsert() method.

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

data_to_upsert = [
    {"id": "row1", "value": 15},  # Update existing row
    {"id": "row3", "value": 30}   # Insert new row
]

# Assuming 'dataset_id' is the ID of the dataset created previously
updated_count = client.upsert("dataset_id", data_to_upsert)
print(f"Upserted {updated_count} rows.")
```

--------------------------------

### SoQL Query Syntax - System Fields

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query referencing system fields like :id and :created_at.

```sql
SELECT :id, :created_at FROM dataset_id
```

--------------------------------

### Minimal Socrata Client Setup

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/07-usage-examples.md

Instantiate a Socrata client for unauthenticated or app-token authenticated access. Use a context manager for automatic client closing.

```python
from sodapy import Socrata

# Unauthenticated access (read-only, rate limited)
client = Socrata("opendata.socrata.com", None)

# With app token (increased rate limits)
client = Socrata("opendata.socrata.com", app_token="MyAppToken")

# Close when done
client.close()

# Or use context manager
with Socrata("opendata.socrata.com", app_token=None) as client:
    results = client.get("dataset_id")
```

--------------------------------

### SoQL SELECT Clause Examples

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/05-soql-query-syntax.md

Demonstrates various ways to use the SELECT clause in SoQL, including retrieving all columns, specific columns, performing aggregations, using column aliases, and creating derived calculations.

```python
# All columns (default)
client.get("dataset_id")
```

```python
# Specific columns
client.get("dataset_id", select="name, amount, date")
```

```python
# Aggregations
client.get("dataset_id", select="sum(amount), count(*), avg(amount)")
```

```python
# Column alias
client.get("dataset_id", select="sum(amount) as total")
```

```python
# Derived calculations
client.get("dataset_id", select="amount * 1.1 as inflated_amount")
```

--------------------------------

### Catalog API - List Datasets Response Example

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/04-endpoints.md

Example JSON response structure for the Catalog API's list datasets endpoint.

```json
{
  "resultSetSize": 100,
  "results": [
    {
      "resource": {
        "id": "dataset_id",
        "name": "Dataset Name",
        "parent_fxf": null,
        "description": "Description"
      },
      "document": {...}
    }
  ]
}
```

--------------------------------

### Usage Examples - Performance Tips (Batch Operations)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Utilizing batch operations for writing data to improve performance compared to single row operations.

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

data_batch = []
for i in range(1000):
    data_batch.append({"id": str(i), "value": i * 2})

# Upsert the entire batch at once
updated_count = client.upsert("dataset_id", data_batch)
print(f"Upserted {updated_count} rows in batch.")
```

--------------------------------

### SoQL Query Syntax - LIMIT and OFFSET

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query with LIMIT and OFFSET clauses for pagination.

```sql
SELECT * FROM dataset_id
LIMIT 100 OFFSET 200
```

--------------------------------

### Usage Examples - Pandas Integration

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Shows how to directly load Socrata data into a Pandas DataFrame for analysis.

```python
from sodapy import Socrata
import pandas as pd

client = Socrata("data.cityofnewyork.us", "your_app_token")

dataset_name = "erm2-nwe9"

# Get data directly into a Pandas DataFrame
results_df = client.get_all(dataset_name, accept="%2Fvnd.openxmlformats-officedocument.spreadsheetml.sheet") # Example for Excel download
# For JSON, use client.get_all() and then convert to DataFrame
# results = client.get_all(dataset_name)
# results_df = pd.DataFrame(results)

# If you get JSON results:
# results = client.get_all(dataset_name)
# results_df = pd.DataFrame(results)

print(results_df.head())
print(f"Loaded {len(results_df)} records into DataFrame.")
```

--------------------------------

### SoQL Query Syntax - SELECT

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query with a SELECT clause, specifying columns to retrieve.

```sql
SELECT column1, column2
FROM dataset_id
```

--------------------------------

### SoQL Query Syntax - ORDER

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query with an ORDER BY clause, sorting the results.

```sql
SELECT * FROM dataset_id
ORDER BY column_name DESC
```

--------------------------------

### Usage Examples - Multi-Domain Operations

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to interact with datasets across different Socrata domains using separate client instances.

```python
from sodapy import Socrata

client_nyc = Socrata("data.cityofnewyork.us", "nyc_app_token")
client_sf = Socrata("data.sfgov.org", "sf_app_token")

# Get data from NYC
nys_data = client_nyc.get("erm2-nwe9", limit=5)
print(f"Retrieved {len(nys_data)} records from NYC.")

# Get data from SF
sf_data = client_sf.get("5zzf-9g2x", limit=5)
print(f"Retrieved {len(sf_data)} records from SF.")

client_nyc.close()
client_sf.close()
```

--------------------------------

### Get Dataset Metadata and Columns

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/07-usage-examples.md

Shows how to retrieve metadata for a specific dataset and iterate through its columns.

```python
# Retrieve metadata
metadata = client.get_metadata("dataset_id")

# Access properties
print(f"Name: {metadata['name']}")
print(f"Description: {metadata['description']}")
print(f"Category: {metadata['category']}")
print(f"Owner: {metadata['owner']['displayName']}")
print(f"Last modified: {metadata['viewLastModified']}")

# List columns
for column in metadata["columns"]:
    print(f"  {column['name']}: {column['dataTypeName']}")

# Get attachments info
attachments = metadata["metadata"].get("attachments", [])
for attachment in attachments:
    print(f"Attachment: {attachment['filename']}")
```

--------------------------------

### Authenticated Socrata Client Setup

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/07-usage-examples.md

Set up a Socrata client for write operations using username/password or for authenticated read access using an OAuth 2.0 token.

```python
# For write operations
client = Socrata(
    "data.cityofnewyork.us",
    app_token="MyAppToken",
    username="user@example.com",
    password="password"
)

# Or with OAuth 2.0
client = Socrata(
    "opendata.socrata.com",
    app_token="MyAppToken",
    access_token="oauth_token_xyz"
)
```

--------------------------------

### SoQL Query Syntax - Response Formats

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Examples of specifying response formats (JSON, CSV, XML) in SoQL queries.

```sql
SELECT * FROM dataset_id.json
SELECT * FROM dataset_id.csv
SELECT * FROM dataset_id.xml
```

--------------------------------

### SOQL ORDER Clause Examples

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/05-soql-query-syntax.md

Sort query results by one or more columns in ascending or descending order. Can be combined with WHERE and LIMIT clauses.

```python
# Ascending (default)
client.get("dataset_id", order="name")
```

```python
# Descending
client.get("dataset_id", order="amount DESC")
```

```python
# Multiple columns
client.get("dataset_id", order="region ASC, amount DESC")
```

```python
# With WHERE and LIMIT
client.get(
    "dataset_id",
    where="status = 'active'",
    order="created_date DESC",
    limit=10
)
```

--------------------------------

### Read All Data from a Dataset

Source: https://github.com/afeld/sodapy/blob/main/README.md

Use `get_all` to read data from a resource, paginating over all results. It returns a generator and accepts the same arguments as `get()`.

```python
>>> client.get_all("nimj-3ivp")
<generator object Socrata.get_all at 0x7fa0dc8be7b0>
```

```python
>>> for item in client.get_all("nimj-3ivp"):
...     print(item)
...
{'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': '{
}', ':updated_meta': '21484', 'earthquake_id': 'c000cnb5', ':created_at': 1348778988}
```

```python
>>> import itertools
>>> items = client.get_all("nimj-3ivp")
>>> first_five = list(itertools.islice(items, 5))
>>> len(first_five)
5
```

--------------------------------

### Get Dataset with SoQL Query

Source: https://github.com/afeld/sodapy/blob/main/README.md

Query a dataset using SoQL syntax for filtering (WHERE) and ordering (ORDER BY). System fields can be included or excluded.

```python
client.get("nimj-3ivp", where="depth > 300", order="magnitude DESC", exclude_system_fields=False)
```

--------------------------------

### SoQL Query with Query String

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/05-soql-query-syntax.md

Build a SoQL query as a single string and pass it to the get() method using the query parameter.

```python
query = """
SELECT
    magnitude,
    region,
    depth
WHERE
    depth > 300
    AND magnitude > 4
ORDER BY
    magnitude DESC
LIMIT
    10
"""
results = client.get("dataset_id", query=query)
```

--------------------------------

### Get Dataset with Field Filter

Source: https://github.com/afeld/sodapy/blob/main/README.md

Retrieve records from a dataset filtered by a specific field value. This example filters by the 'region' field.

```python
client.get("nimj-3ivp", region="Kansas")
```

--------------------------------

### get

Source: https://github.com/afeld/sodapy/blob/main/README.md

Retrieve data from the requested resources. Filter and query data by field name, id, or using [SoQL keywords](https://dev.socrata.com/docs/queries/).

```APIDOC
## get(dataset_identifier, content_type="json", **kwargs)

Retrieve data from the requested resources. Filter and query data by field name, id, or using [SoQL keywords](https://dev.socrata.com/docs/queries/).

    >>> client.get("nimj-3ivp", limit=2)
    [{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'}, {...}]

    >>> client.get("nimj-3ivp", where="depth > 300", order="magnitude DESC", exclude_system_fields=False)
    [{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'{
}', u':updated_meta': u'21484', u'earthquake_id': u'c000cnb5', u':created_at': 1348778988}, {...}]

    >>> client.get("nimj-3ivp/193", exclude_system_fields=False)
    {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'{
}', u':updated_meta': u'21484', u':position': 193, u'earthquake_id': u'c000cmsq', u':created_at': 1348778988}

    >>> client.get("nimj-3ivp", region="Kansas")
    [{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'}, {...}]
```

--------------------------------

### Initialize Socrata Client

Source: https://github.com/afeld/sodapy/blob/main/examples/basic_queries.ipynb

Creates a Socrata client instance and prints connection details. Ensure the domain and token are correctly set.

```python
client = Socrata(socrata_domain, socrata_token)
print("Domain: {domain:} \nSession: {session:} \nURI Prefix: {uri_prefix:}".format(**client.__dict__))
```

--------------------------------

### Get Data with Socrata Client

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Retrieve a limited number of records from a dataset using the get() method.

```python
from sodapy import Socrata

client = Socrata("data.cityofnewyork.us", "your_app_token")

# Get the first 5 results
results = client.get("erm2-nwe9", limit=5)

# Results is a list of dictionaries
print(results)
```

--------------------------------

### Querying Data with Socrata Client

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Shows how to retrieve specific data subsets from a dataset using the `get` method. You can specify columns and filter rows with SoQL parameters.

```python
# Query data
client.get("dataset_id", select="col1, col2", where="col1 > 100")
```

--------------------------------

### Initialize Socrata Client

Source: https://github.com/afeld/sodapy/blob/main/README.md

Set up a connection to the Socrata API with authentication and custom timeout. Username and password are required for data modification.

```python
from sodapy import Socrata
client = Socrata(
    "sandbox.demo.socrata.com",
    "FakeAppToken",
    username="fakeuser@somedomain.com",
    password="mypassword",
    timeout=10
)
```

--------------------------------

### Usage Examples - Writing Data (Delete)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of deleting specific rows from a dataset by their unique IDs using delete().

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

ids_to_delete = ["row1", "row3"] # IDs of rows to delete

# Delete rows from 'dataset_id'
deleted_count = client.delete("dataset_id", ids_to_delete)
print(f"Deleted {deleted_count} rows.")
```

--------------------------------

### Initialize Socrata Client

Source: https://github.com/afeld/sodapy/blob/main/examples/soql_queries.ipynb

Sets up the Socrata client with the domain and dataset identifier. An application token can be optionally provided via an environment variable.

```python
socrata_domain = "opendata.socrata.com"
socrata_dataset_identifier = "f92i-ik66"

# If you choose to use a token, run the following command on the terminal (or add it to your .bashrc)
# $ export SODAPY_APPTOKEN=<token>
socrata_token = os.environ.get("SODAPY_APPTOKEN")
```

--------------------------------

### Initialize Socrata Client with Context Manager

Source: https://github.com/afeld/sodapy/blob/main/README.md

Use a context manager for client initialization to ensure proper resource management and automatic teardown.

```python
with Socrata("sandbox.demo.socrata.com", None) as client:
    # do some stuff
```

--------------------------------

### List Datasets with Filters

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/07-usage-examples.md

Demonstrates how to list datasets using various filters like limit, categories, tags, text search, and visibility.

```python
# All datasets on domain
datasets = client.datasets()
print(f"Found {len(datasets)} datasets")

# Limit results
datasets = client.datasets(limit=10)

# Filter by category
datasets = client.datasets(categories=["Finance", "Transportation"])

# Filter by tags
datasets = client.datasets(tags=["environment", "climate"])

# Search by text
datasets = client.datasets(q="crime")

# Filter by visibility
public_datasets = client.datasets(public=True)
```

--------------------------------

### get()

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Retrieve data from a dataset with optional filtering.

```APIDOC
## get()

### Description
Retrieve data from a dataset with optional filtering.

### Signature
```python
def get(
    self,
    dataset_identifier: str,
    content_type: str = "json",
    **kwargs
) -> Union[list, dict, bytes]
```

### Parameters
#### Path Parameters
None

#### Query Parameters
- **dataset_identifier** (str) - Required - Identifier for the dataset.
- **content_type** (str) - Optional - The desired content type for the response (e.g., "json", "csv", "xml"). Defaults to "json".
- **kwargs**: Additional parameters for filtering and querying.

### Request Example
```python
# Example usage (assuming socrata_client is an initialized Socrata client instance)
socrata_client.get("your_dataset_identifier", limit=500, where="column_name='value'")
```

### Response
#### Success Response
- **list or dict** (JSON): Data in JSON format.
- **list of lists** (CSV): Data in CSV format.
- **bytes** (XML): Data in XML format.
```

--------------------------------

### Get Dataset Metadata

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Retrieve metadata for a specific dataset using the get_metadata() method.

```python
from sodapy import Socrata

client = Socrata("data.cityofnewyork.us", "your_app_token")

metadata = client.get_metadata("erm2-nwe9")

# Metadata is a dictionary
print(metadata)
```

--------------------------------

### SoQL Query Syntax - GROUP

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query with a GROUP BY clause, aggregating results.

```sql
SELECT COUNT(*) as count, column_name
FROM dataset_id
GROUP BY column_name
```

--------------------------------

### Instantiate Socrata Client (Basic Auth)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/00-START-HERE.txt

Use basic authentication with a username and password for write operations. Requires an app token as well.

```python
Socrata("domain.com", "app_token", username="x", password="y")
```

--------------------------------

### SoQL Query Syntax - WHERE

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query with a WHERE clause, filtering records based on a condition.

```sql
SELECT * FROM dataset_id
WHERE column_name = 'some_value'
```

--------------------------------

### Socrata Client Initialization

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/00-START-HERE.txt

Demonstrates various ways to initialize the Socrata client, including unauthenticated access, using an app token, basic authentication, and OAuth.

```APIDOC
## Socrata Client Initialization

### Description
Initializes the Socrata client with different authentication methods.

### Constructor
`Socrata(domain, app_token, username=None, password=None, access_token=None)`

### Parameters
- **domain** (string) - The domain of the Socrata instance.
- **app_token** (string or None) - An application token for faster requests. If None, unauthenticated access is used.
- **username** (string, optional) - Username for basic authentication (write operations).
- **password** (string, optional) - Password for basic authentication (write operations).
- **access_token** (string, optional) - Access token for OAuth authentication (write operations).

### Examples

#### Unauthenticated (read-only)
```python
Socrata("domain.com", None)
```

#### With app token (faster)
```python
Socrata("domain.com", "app_token")
```

#### With basic auth (write)
```python
Socrata("domain.com", "app_token", username="x", password="y")
```

#### With OAuth (write)
```python
Socrata("domain.com", "app_token", access_token="token")
```
```

--------------------------------

### Listing Datasets

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Illustrates how to list available datasets using the `datasets` method. You can control the number of results with the `limit` parameter.

```python
# List datasets
datasets = client.datasets(limit=10)
```

--------------------------------

### Initialize Socrata Client (No Auth)

Source: https://github.com/afeld/sodapy/blob/main/README.md

Create a basic client without authentication, suitable for read-only operations. Note that this may be subject to stricter rate limits.

```python
client = Socrata("sandbox.demo.socrata.com", None)
```

--------------------------------

### Update Dataset Metadata

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/07-usage-examples.md

Provides an example of updating the metadata for a dataset, such as its category, description, and attribution link.

```python
updates = {
    "category": "Public Safety",
    "description": "Updated description",
    "attributionLink": "https://example.com"
}
updated_metadata = client.update_metadata("dataset_id", updates)
print("Metadata updated")
```

--------------------------------

### Create New Dataset

Source: https://github.com/afeld/sodapy/blob/main/README.md

Use `create` to make a new dataset. Optionally provide `description`, `columns`, `category`, `tags`, `row_identifier`, and `new_backend`.

```python
>>> columns = [{"fieldName": "delegation", "name": "Delegation", "dataTypeName": "text"}, {"fieldName": "members", "name": "Members", "dataTypeName": "number"}]
>>> tags = ["politics", "geography"]
>>> client.create("Delegates", description="List of delegates", columns=columns, row_identifier="delegation", tags=tags, category="Transparency")
{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 }, ... }
```

--------------------------------

### SoQL Query Syntax - Full-Text Search

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query using the :contains() operator for full-text search.

```sql
SELECT * FROM dataset_id
WHERE column_name :contains 'search term'
```

--------------------------------

### Instantiate Socrata Client (App Token)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/00-START-HERE.txt

Instantiate the client with an app token for faster, rate-limited access. This is recommended for most read operations.

```python
Socrata("domain.com", "app_token")
```

--------------------------------

### Get Dataset with Limit

Source: https://github.com/afeld/sodapy/blob/main/README.md

Retrieve a limited number of records from a dataset. Useful for quick previews or testing queries.

```python
client.get("nimj-3ivp", limit=2)
```

--------------------------------

### Socrata Client Constructor

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Initializes the Socrata client with domain and authentication details.

```APIDOC
## Socrata Constructor

### Description
Initializes the Socrata client with domain and authentication details.

### Signature
```python
Socrata(
    domain: str,
    app_token: Optional[str],
    username: Optional[str] = None,
    password: Optional[str] = None,
    access_token: Optional[str] = None,
    session_adapter: Optional[dict] = None,
    timeout: int | float = 10
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Attributes
- `domain` (str): The Socrata domain
- `session` (requests.Session): Underlying HTTP session
- `timeout` (int or float): Request timeout in seconds
- `uri_prefix` (str): Protocol prefix (default "https://")
- `DEFAULT_LIMIT` (int): Default row limit for queries (1000)
```

--------------------------------

### Get All Dataset Data

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Iterate through all pages of a dataset to retrieve all records. Returns a generator yielding row objects.

```python
def get_all(
    self,
    dataset_identifier: str,
    content_type: str = "json",
    **kwargs
) -> Generator[dict, None, None]
```

--------------------------------

### GET - List Datasets

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/04-endpoints.md

Lists datasets available on a domain, supporting various filtering, searching, and sorting options.

```APIDOC
## GET - List Datasets

### Description
List datasets on a domain with filtering and search capabilities. Allows for detailed querying of the dataset catalog.

### Method
GET

### Endpoint
`GET https://{domain}/api/catalog/v1`

### Parameters
#### Query Parameters
- **domains** (string) - Yes - Domain filter.
- **limit** (integer) - No - Maximum number of results to return.
- **offset** (integer) - No - The starting offset for results.
- **order** (string) - No - Field to sort the results by.
- **ids** (string) - Yes - Filter by specific dataset IDs.
- **categories** (string) - Yes - Filter by dataset categories.
- **tags** (string) - Yes - Filter by dataset tags.
- **only** (string) - Yes - Filter by logical types (e.g., dataset, api, file).
- **shared_to** (string) - Yes - Filter by user/team IDs or "site" for shared datasets.
- **column_names** (string) - Yes - Filter for datasets containing specific column names.
- **q** (string) - No - Text search query.
- **min_should_match** (string) - No - Elasticsearch match percentage.
- **attribution** (string) - No - Filter by organization name.
- **license** (string) - No - Filter by license type.
- **derived_from** (string) - No - Filter by parent dataset ID.
- **provenance** (string) - No - Filter by provenance ("official" or "community").
- **for_user** (string) - No - Filter by owner user ID.
- **visibility** (string) - No - Filter by visibility ("open" or "internal").
- **public** (boolean) - No - Filter for public or private datasets.
- **published** (boolean) - No - Filter by published status.
- **approval_status** (string) - No - Filter by approval pipeline status.
- **explicitly_hidden** (boolean) - No - Filter for hidden datasets.
- **derived** (boolean) - No - Filter for derived datasets.

### Response
#### Success Response (200)
- **resultSetSize** (integer) - The total number of results.
- **results** (array) - An array of dataset objects. Each object contains:
  - **resource** (object)
    - **id** (string) - The dataset ID.
    - **name** (string) - The dataset name.
    - **parent_fxf** (string/null) - The parent dataset ID if applicable.
    - **description** (string) - The dataset description.
  - **document** (object) - Additional document details.

#### Error Response
- **400 Bad Request**: Invalid parameters provided.

### Used by
`Socrata.datasets()`
```

--------------------------------

### create()

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Creates a new dataset with the specified name and optional parameters.

```APIDOC
## create()

### Description
Creates a new dataset.

### Method
POST (assumed based on create operation)

### Endpoint
/datasets

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (str) - Required - The name of the new dataset.
- **kwargs** (dict) - Optional - Additional parameters for dataset creation.

### Request Example
```json
{
  "name": "my_new_dataset",
  "description": "This is a test dataset"
}
```

### Response
#### Success Response (200)
- **metadata** (dict) - Dictionary containing the metadata of the newly created dataset.

#### Response Example
```json
{
  "id": "dataset_id_123",
  "name": "my_new_dataset",
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Get All Data with Socrata Client

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Retrieve all records from a dataset using the get_all() method. Be cautious with large datasets.

```python
from sodapy import Socrata

client = Socrata("data.cityofnewyork.us", "your_app_token")

# Get all results (can be memory intensive for large datasets)
results = client.get_all("erm2-nwe9")

# Results is a list of dictionaries
print(f"Retrieved {len(results)} records.")
```

--------------------------------

### Initialize Socrata Client (Basic HTTP Authentication)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/02-configuration.md

Use this for write operations (create, upsert, replace, delete). Both username and password must be provided. This method is deprecated in favor of OAuth 2.0.

```python
client = Socrata(
    "domain.com",
    app_token="YOUR_APP_TOKEN",
    username="user@example.com",
    password="your_password"
)
```

--------------------------------

### Usage Examples - Error Handling (Specific Exception)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Catching specific exceptions like sodapy.errors.SocrataAPIError for detailed error handling.

```python
from sodapy import Socrata
from sodapy.errors import SocrataAPIError

client = Socrata("data.cityofnewyork.us", "your_app_token")

try:
    # Example: Invalid SoQL query
    client.get("erm2-nwe9", query="SELECT INVALID SYNTAX")
except SocrataAPIError as e:
    print(f"Caught a Socrata API error: {e}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
```

--------------------------------

### Socrata Class Constructor

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Instantiate the Socrata client with various configuration options including domain, app token, and authentication methods.

```python
from sodapy import Socrata

# Example with app token
client = Socrata("data.cityofnewyork.us", "your_app_token")

# Example with basic auth
# client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

# Example with OAuth2
# client = Socrata("your.domain.com", "your_app_token",
#                  username="user", password="password",
#                  auth_type="oauth", token_path="/oauth/token",
#                  client_id="your_client_id", client_secret="your_client_secret")
```

--------------------------------

### Create New Dataset

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Create a new dataset using the create() method. Requires appropriate permissions.

```python
from sodapy import Socrata

client = Socrata("your.domain.com", "your_app_token", username="user", password="password")

# Define dataset metadata and schema
dataset_metadata = {
    "name": "My New Dataset",
    "description": "This is a dataset created via the API."
}
dataset_schema = {
    "columns": [
        {"name": "id", "dataTypeName": "text"},
        {"name": "value", "dataTypeName": "number"}
    ]
}

# Create the dataset
created_dataset_info = client.create(dataset_metadata, dataset_schema)
print(created_dataset_info)
```

--------------------------------

### Initialize Socrata Client (No Authentication)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/02-configuration.md

Use this method for read-only access to public datasets. Strict throttling limits apply, and a warning is logged if an app_token is not provided.

```python
client = Socrata("domain.com", None)
```

--------------------------------

### Initialize Socrata Client (OAuth 2.0)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/01-socrata-class.md

Initialize a Socrata client using OAuth 2.0 access token for authentication. This is the recommended method for authentication.

```python
# Client with OAuth 2.0
client = Socrata(
    "opendata.socrata.com",
    app_token="MyAppToken123",
    access_token="oauth_access_token_value"
)
```

--------------------------------

### Initialize Socrata Client (App Token Only)

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/02-configuration.md

This method increases rate limits for read operations. Obtain an app token by creating an account on the Socrata domain.

```python
client = Socrata("domain.com", app_token="YOUR_APP_TOKEN")
```

--------------------------------

### SoQL Query Syntax - Column Filtering

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/MANIFEST.txt

Example of a SoQL query filtering based on the presence or absence of a value in a column.

```sql
SELECT * FROM dataset_id
WHERE column_name IS NOT NULL
```

--------------------------------

### Retrieving All Data from a Dataset

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Illustrates how to fetch all rows from a dataset using `get_all`. This is useful for iterating through large datasets, but be mindful of performance.

```python
# Get all data
for row in client.get_all("dataset_id"):
    process(row)
```

--------------------------------

### Socrata Client Constructor

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Instantiate the Socrata client with domain and authentication details. Supports optional app token, username, password, access token, session adapter, and timeout.

```python
Socrata(
    domain: str,
    app_token: Optional[str],
    username: Optional[str] = None,
    password: Optional[str] = None,
    access_token: Optional[str] = None,
    session_adapter: Optional[dict] = None,
    timeout: int | float = 10
)
```

--------------------------------

### Common Operations

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/08-api-reference-index.md

Provides examples of frequently used operations with the Socrata client, such as querying, inserting, updating, deleting, and retrieving metadata.

```APIDOC
## Common Operations

### Query data
```python
client.get("dataset_id", select="col1, col2", where="col1 > 100")
```

### Get all data
```python
for row in client.get_all("dataset_id"):
    process(row)
```

### Insert data
```python
client.upsert("dataset_id", [{"col1": "val1"}])
```

### Update data
```python
client.upsert("dataset_id", [{':id': 42, "col1": "new_val"}])
```

### Delete row
```python
client.delete("dataset_id", row_id=42)
```

### Get metadata
```python
metadata = client.get_metadata("dataset_id")
```

### List datasets
```python
datasets = client.datasets(limit=10)
```
```

--------------------------------

### create

Source: https://github.com/afeld/sodapy/blob/main/_autodocs/01-socrata-class.md

Creates a new dataset with specified metadata and columns. It allows setting a name, description, columns, category, tags, and a row identifier.

```APIDOC
## create(name, **kwargs)

### Description
Creates a new dataset with specified metadata and columns. It allows setting a name, description, columns, category, tags, and a row identifier.

### Method
POST

### Endpoint
/api/v1/datasets

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - Dataset name
- **description** (string) - Optional - Dataset description
- **columns** (list) - Optional - List of column definitions, each with "fieldName", "name", "dataTypeName"
- **category** (string) - Optional - Dataset category (must exist in domain metadata)
- **tags** (list) - Optional - List of tag strings
- **row_identifier** (string) - Optional - Field name to use as primary key
- **new_backend** (bool) - Optional - Whether to create in the new backend

### Request Example
```python
columns = [
    {"fieldName": "delegation", "name": "Delegation", "dataTypeName": "text"},
    {"fieldName": "members", "name": "Members", "dataTypeName": "number"}
]
tags = ["politics", "geography"]

response = client.create(
    "Delegates",
    description="List of delegates",
    columns=columns,
    row_identifier="delegation",
    tags=tags,
    category="Transparency"
)

dataset_id = response["id"]
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created dataset.
- **name** (string) - The name of the dataset.
- **description** (string) - The description of the dataset.

#### Response Example
```json
{
  "id": "dataset_id_123",
  "name": "Delegates",
  "description": "List of delegates"
}
```

### Errors
- **HTTPError (requests)** - Invalid request or insufficient permissions
```

--------------------------------

### Get Specific Resource by ID

Source: https://github.com/afeld/sodapy/blob/main/README.md

Retrieve a single resource (row) from a dataset using its identifier. System fields are included by default.

```python
client.get("nimj-3ivp/193", exclude_system_fields=False)
```