Using the SODA3 API

Overview

This article provides examples of common SODA2 query patterns and their SODA3 equivalents. Whether you're building integrations, performing data analysis, or exploring public datasets, these examples will help you understand when and how to use SODA3.

For a conceptual overview of SODA3 and why it was introduced, see Introducing the new SODA3 API.

Coming from SODA1? SODA1 (/views/{4x4}/rows, /api/views/{4x4}/rows) is deprecated and will be permanently removed on 12/16/2026. Use the mapping below to move similar query patterns to SODA3.

What is SODA3

The new SODA3 API is designed to make working with your data simpler and more reliable. With improved performance, smarter caching, and clearer error handling, it's now easier than ever to build exactly what you need. For more technical details you can check our dev site, https://dev.socrata.com/docs/endpoints

Here's what you'll notice right away:

• Improved Performance - Our updated query endpoint provides the best performance and clearer error handling especially for complex queries.

• Cleaner queries – No more stitching together "$" parameters. You can now write straightforward SoQL queries or send larger requests as a JSON payload.

• Simplified results – Paging and limits are easier to manage directly within your query, reducing complexity.

• Clearer identification – Every request now shows who is making the call, helping the system better support your use case and deliver more consistent results.

Understanding SODA3 Endpoints

SODA3 introduces two primary endpoints:

Query Endpoint: /api/v3/views/{id}/query.{format}

• Purpose: Machine-readable responses for application integration

• Formats: JSON, CJSON, NDJSON (newline-delimited), GeoJSON, CSV, TSV, XML

• Methods: GET (with ?query= parameter and full query syntax) or POST (with JSON body)

• Use cases: Building applications, dashboards, integrations

• Authentication: Required (app token or user credentials)

Important Note: SODA3 does not support the fragmented query syntax from SODA2 (separate $where, $select, $limit parameters). Instead, write complete SoQL queries using the ?query= parameter or POST a JSON body with a query field.

Export Endpoint: /api/v3/views/{id}/export.{format}

• Purpose: Human-readable data exports in various formats

• Formats: CSV, TSV, XLSX, KML, KMZ

• Methods: GET

• Use cases: Downloading datasets, generating reports

• Authentication: Required for filtered exports; not required for full public dataset exports

When to Use Each Endpoint

Authentication and App Tokens

Full exports via /api/v3/views/{id}/export do not require authentication for public datasets.

Filtered exports or query endpoints require authentication:

• Include an app token: $$app_token=YOUR_TOKEN or X-App-Token header

• Or use OAuth authentication

Register for an app token to get started.

Pagination: SODA3 vs SODA2

SODA2 used explicit $limit and $offset parameters.

SODA3 improves pagination by automatically imposing a total order on results.

Using SODA3 Pagination (POST)

POST /api/v3/views/{id}/query.json

{
  "query": "SELECT * WHERE status='active'",
  "page": {
    "pageSize": 1000,
    "pageNumber": 1
  }
}

Increment pageNumber for subsequent pages (1, 2, 3...).

Best Practice: Keyset Pagination

For the most efficient pagination, use keyset pagination instead:

SELECT * WHERE primary_key > 'last_value' ORDER BY primary_key LIMIT 1000

This approach is:

• Faster than offset-based pagination

• More efficient on large datasets

Recommendation: Use SODA3's built-in pagination when you cannot use keyset pagination. For high-performance applications, use keyset pagination when possible.

Examples

Example 1: Full Dataset Export

Use Case: Download complete dataset as CSV for offline analysis

SODA2:

GET /resource/abc-1234.csv

SODA3:

GET /api/v3/views/abc-1234/export.csv

Auth: Not required for public datasets

Example 2: Filtered Export

Use Case: Download subset of records for reporting

SODA2:

GET /resource/abc-1234.json?$where=state_code='NY'&$limit=1000

SODA3:

GET /api/v3/views/abc-1234/export.json?query=SELECT * WHERE state_code='NY' LIMIT 1000

Auth: Required

Note: SODA3 requires complete SoQL queries in the ?query= parameter, not fragmented $where, $limit parameters.

Example 3: Simple Query with GET

Use Case: Quick API test to retrieve specific records

SODA2:

GET /resource/abc-1234.json?$where=property_type='PA'&$limit=1

SODA3:

GET /api/v3/views/abc-1234/query.json?query=SELECT * WHERE property_type='PA' LIMIT 1

Auth: Required

Example 4: Query with POST

Use Case: Application integration for filtered data

SODA2:

GET /resource/abc-1234.json?$where=state_code='CA'&$limit=10

SODA3:

POST /api/v3/views/abc-1234/query.json
Content-Type: application/json

{
  "query": "SELECT * WHERE state_code='CA' LIMIT 10"
}

Auth: Required

Best Practice: Use POST for production applications - it allows longer queries.

Example 5: Date Range Filtering

Use Case: Daily report for specific date range

SODA2:

GET /resource/abc-1234.json?$where=date>='2026-07-12T00:00:00' AND date<='2026-07-12T23:59:59'&$order=date ASC&$limit=1000

SODA3:

POST /api/v3/views/abc-1234/query.json

{
  "query": "SELECT * WHERE date >= '2026-07-12T00:00:00' AND date <= '2026-07-12T23:59:59' ORDER BY date ASC LIMIT 1000"
}

Auth: Required

Example 6: Aggregation - Count

Use Case: Get total record count without downloading data

SODA2:

GET /resource/abc-1234.json?$select=count(*) as c

SODA3:

POST /api/v3/views/abc-1234/query.json

{
  "query": "SELECT count(*) as c"
}

Auth: Required

Example 7: Ordering and Pagination

Use Case: Get most recent records with pagination

SODA2:

GET /resource/abc-1234.json?$order=:id DESC&$limit=50&$offset=0
GET /resource/abc-1234.json?$order=:id DESC&$limit=50&$offset=50

SODA3:

POST /api/v3/views/abc-1234/query.json

{
  "query": "SELECT * ORDER BY :id DESC",
  "page": {
    "pageSize": 50,
    "pageNumber": 1
  }
}

Then increment pageNumber for subsequent pages.

Auth: Required

Example 8: Complex Query with Multiple Clauses

Use Case: Filtered query with specific columns, filtering, and sorting

SODA2:

GET /resource/abc-1234.json?$select=report_date,market_name,open_interest&$where=market_name like 'EURO FX%'&$order=report_date DESC&$limit=20

SODA3:

POST /api/v3/views/abc-1234/query.json

{
  "query": "SELECT report_date, market_name, open_interest WHERE market_name like 'EURO FX%' ORDER BY report_date DESC LIMIT 20"
}

Auth: Required

Best Practices Summary

1. Use export for downloads - Use /export endpoint when downloading datasets as files (CSV, Excel, etc.)

2. Use query for integrations - Use /query endpoint when building applications that consume JSON data

3. Prefer POST for queries - POST method recommended for production applications

4. Write complete SoQL queries - SODA3 doesn't support fragmented syntax ($where, $select, $limit as separate parameters)

5. Consider keyset pagination for performance - WHERE primary_key > last_value ORDER BY primary_key is faster

6. Choose the right CSV endpoint - Use /query.csv for machine processing which has a standard format across datasets and views, /export.csv for human-readable report which honors the views formatting.

Additional Resources

• SODA3 Endpoints Documentation

• SoQL Functions Reference

• Authentication Documentation

• App Token Registration