# Socrata Open Data Search: Datasets and Rows | $1/1K (`one_dollar_store/socrata-open-data-search`) Actor

$1 per 1,000 results, platform usage included. Search any Socrata open data portal for datasets, or read the rows of one dataset with filters (SoQL). City, county, state and agency portals worldwide. No key needed at low volume. Not limited to permits.

- **URL**: https://apify.com/one_dollar_store/socrata-open-data-search.md
- **Developed by:** [One Dollar Store](https://apify.com/one_dollar_store) (community)
- **Categories:** Other, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Socrata Open Data Search: Find Datasets and Read Rows on Any Portal

**$1 per 1,000 results. Platform usage included. No rental, no minimum.**

[Open it in Apify Console](https://console.apify.com/actors/1sOpFaaHdkzF67lYj/input)

### What it costs

| Results | Price |
|---|---|
| 1,000 | $1.00 |
| 10,000 | $10.00 |
| 100,000 | $100.00 |

Plus $0.001 per run. One flat price, platform usage included, so there is no separate compute or proxy bill. A result is one dataset when you search the catalog, or one row when you read a dataset. A daily run that reads the 500 newest rows of a dataset costs $0.501, about $15.03 for 30 days.

### What it does

Socrata is the software behind the open data portals of many cities, counties, states and agencies, such as data.cityofchicago.org and data.ny.gov. This actor does two jobs on any of them:

1. **Find datasets.** Search by words, optionally on one portal, and get one row per dataset with its name, description, columns, category, tags, dates, views and links.
2. **Read rows.** Give a portal domain and a dataset ID, add optional filters, and get the dataset's rows.

It is not tied to one subject. If you only want issued building permits from US city portals in one common layout, use the [Building Permits Scraper](https://apify.com/one_dollar_store/city-building-permits-scraper) from this store instead. This actor does not repeat it: it reads any dataset in the portal's own columns.

### Why use it

- **Any Socrata portal.** One input works for a city, a county, a state or a federal agency portal.
- **Find first, then read.** The dataset rows list every column with its field name and type, so you can write the filter for the second run without leaving Apify.
- **Real filters.** Rows can be filtered, trimmed to chosen columns, ordered and grouped with Socrata's own query language (SoQL), so a count by category is one run.
- **No key at low volume.** The public APIs work without a token. If a portal throttles you, paste your own free app token in the optional field.
- **Safe with domains.** Only public https portal addresses are read, never private or local ones.

### Quick start

1. Open the actor, enter a portal domain such as `data.cityofchicago.org` and search words such as `building permits`, press **Start**. You get a list of datasets.
2. Copy a `datasetId` from the results, put it in **Dataset ID**, press **Start** again. You get that dataset's rows.
3. Download the results as JSON, CSV or Excel, or read them through the API.

```json
{ "domain": "data.cityofchicago.org", "searchQuery": "building permits", "maxItems": 20 }
```

### Use it from code

```bash
curl -X POST "https://api.apify.com/v2/acts/one_dollar_store~socrata-open-data-search/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "data.cityofchicago.org", "datasetId": "ydr8-5enu", "where": "issue_date > '"'"'2026-09-01'"'"'", "maxItems": 100}'
```

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("one_dollar_store/socrata-open-data-search").call(
    run_input={
        "domain": "data.cityofchicago.org",
        "datasetId": "ydr8-5enu",
        "where": "issue_date > '2026-09-01'",
        "maxItems": 100,
    }
)
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row.get("issue_date"), row.get("permit_type"), row.get("street_name"))
```

### Use it from an AI assistant

Claude, ChatGPT, Cursor and other assistants can call this actor through Apify's MCP server. Add it with this server address:

```
https://mcp.apify.com?tools=one_dollar_store/socrata-open-data-search
```

Then ask, for example: "Search data.cityofchicago.org for datasets about food inspections, then read the 50 newest rows of the best match."

### Switching from another Socrata actor

Most Socrata actors take a portal domain, a dataset ID and a SoQL query. Here they are `domain`, `datasetId`, and the SoQL parts `where`, `select`, `group` and `order`. Dataset search takes `searchQuery`. Rows come back with the portal's own column names, as the SODA API sends them.

### Input

| Field | Type | Default | What it does |
|---|---|---|---|
| `domain` | text | none | Portal domain such as `data.cityofchicago.org`. Optional for dataset search, required for rows. A pasted dataset page address also works and fills in the dataset ID. |
| `datasetId` | text | none | Fill it to read rows. Four characters, a dash, four characters, for example `ydr8-5enu`. Empty means dataset search. |
| `searchQuery` | text | none | Search words for dataset names, descriptions and column names. |
| `assetType` | text | `dataset` | `dataset`, `all`, `map`, `chart`, `file`, `href` (external link) or `story`. |
| `category`, `tags` | text, list | none | Portal category (as the portal spells it) and tags (all must match). |
| `sortBy` | text | `relevance` | `relevance`, `page_views_total`, `page_views_last_month`, `updatedAt`, `createdAt` or `name`. |
| `region` | text | `us` | `us` or `eu`: which Socrata catalog lists the portal. |
| `where` | text | none | Rows only: a SoQL condition, for example `issue_date > '2026-09-01'`. |
| `select` | text | all columns | Rows only: comma separated columns, or functions such as `count(*)` with `group`. |
| `group`, `order` | text | none | Rows only: SoQL group and order, for example `issue_date DESC`. |
| `rowSearchText` | text | none | Rows only: keeps rows where any text column contains these words. |
| `appToken` | text | none | Optional. Your own free Socrata app token, for portals that throttle anonymous requests. |
| `maxItems` | number | 100 | Total results for the run. Minimum 10, maximum 10,000. |

### Output fields

Searching for datasets gives one row per dataset:

| Field | Meaning |
|---|---|
| `datasetId`, `name`, `description`, `domain` | The dataset ID, its name, the publisher's description and the portal that hosts it. |
| `assetType`, `category`, `tags` | Kind of item (`dataset`, `map`, `chart`, `file`, `href`, `story`), the portal's category and the publisher's tags. |
| `attribution`, `attributionLink`, `license`, `ownerName` | Who the portal credits, a link, the license text when there is one, and the portal account that owns the dataset. |
| `createdAt`, `updatedAt`, `dataUpdatedAt`, `metadataUpdatedAt` | When the dataset was created, last changed, last had its data refreshed and last had its description edited. |
| `pageViewsTotal`, `pageViewsLastMonth`, `downloadCount` | View and download counts kept by the portal. |
| `columnCount`, `columns` | Number of columns and the first 300 of them, each with `name`, `fieldName` (use it in filters), `type` and `description`. |
| `customMetadata` | Extra fields the publisher filled in, such as update frequency or data owner. |
| `portalUrl`, `apiEndpoint` | The dataset page and its API address. |
| `scrapedAt` | When the actor read the record. |

Fields a dataset does not have are left out.

Reading rows gives one row per record, with the columns of that dataset exactly as the portal names them. Values are as the portal sends them: numbers come as text (`"200000"`), dates as `2026-10-18T00:00:00.000`, and location columns as a small object with `type` and `coordinates`. Columns whose names start with a colon (system and computed region columns) are left out.

### Sample results

Real results from test runs on 20 October 2026, with long text shortened and some fields left out.

A dataset found by search (the column list cut to two entries):

```json
{
  "datasetId": "ydr8-5enu",
  "name": "Building Permits",
  "domain": "data.cityofchicago.org",
  "assetType": "dataset",
  "category": "Buildings",
  "tags": [
    "buildings",
    "permits"
  ],
  "attribution": "City of Chicago",
  "updatedAt": "2026-10-19T12:27:02.000Z",
  "pageViewsTotal": 5696855,
  "downloadCount": 170120,
  "columnCount": 122,
  "columns": [
    {
      "name": "PERMIT_TYPE",
      "fieldName": "permit_type",
      "type": "Text",
      "description": "Type of permit"
    },
    {
      "name": "ISSUE_DATE",
      "fieldName": "issue_date",
      "type": "Calendar date",
      "description": "For most permit types, date when City determined permit was ready to issue, subject to payment of permit fees; For Express Permit Program, date when permit issued based on full payment of applicable permit fee"
    }
  ],
  "portalUrl": "https://data.cityofchicago.org/d/ydr8-5enu",
  "apiEndpoint": "https://data.cityofchicago.org/resource/ydr8-5enu.json"
}
```

Rows of the Chicago building permits dataset, filtered to cost above 100,000 and issued after 1 September, newest first:

```json
[
  {
    "permit_": "101085337",
    "permit_type": "PERMIT - RENOVATION/ALTERATION",
    "issue_date": "2026-10-18T00:00:00.000",
    "work_description": "SPR 2019 CBCERECT REAR 2 STORY FRAME ADDITION, INTERIOR REHABILITATION AND NEW REAR OPEN W ...",
    "reported_cost": "200000",
    "street_name": "BERENICE AVE"
  },
  {
    "permit_": "101078696",
    "permit_type": "PERMIT - RENOVATION/ALTERATION",
    "issue_date": "2026-10-16T00:00:00.000",
    "work_description": "DDS 2019 CBRC: INTERIOR TENANT IMPROVEMENT TO EXISTING ONE STORY BUILDING FOR \"TESLA, INC. ...",
    "reported_cost": "2490632",
    "street_name": "LOOMIS ST"
  }
]
```

The same dataset grouped by permit type, the first three groups after the largest one (`select` is `permit_type, count(*) as permits`, `group` is `permit_type`):

```json
[
  {
    "permit_type": "PERMIT - EASY PERMIT PROCESS",
    "permits": "207651"
  },
  {
    "permit_type": "PERMIT - RENOVATION/ALTERATION",
    "permits": "168099"
  },
  {
    "permit_type": "PERMIT - SIGNS",
    "permits": "55257"
  }
]
```

### Limits

- **Up to 10,000 results per run.** That is the cap for dataset search and for reading rows. To read more of a big dataset, split it with `where`, for example by date range, and run once per range.
- **Big reads take minutes.** Results are saved one at a time. A test read of 2,500 rows of a 122 column dataset took about five minutes, so 10,000 wide rows can take most of the default time limit of one hour. Narrow reads with `select` are faster. If a run reaches the limit it stops cleanly and keeps what it has; raise Timeout under Run options for more.
- **Rows come as the portal sends them.** There is no renaming, no type conversion and no joining of datasets. Numbers and dates arrive as text, as above.
- **The dataset must be a table.** Maps, charts, files, external links and stories show up in dataset search with `assetType` set to `all` or their own type, but only tables have rows. A private or removed dataset returns no rows and a note in the run log.
- **Column names must be exact.** Filters use the `fieldName` of a column, lower case with underscores. A filter the portal cannot parse ends the run with no rows and the portal's own message in the log.
- **Throttling.** Portals limit anonymous requests. The actor retries a throttled or failed request up to three times and honours the portal's wait time. If a run still reports throttling, paste your own free app token from the portal's developer settings into the optional field.
- **Order while paging.** Rows are read in pages of up to 1,000 and ordered by the portal's row ID so no row is read twice. A few datasets cannot be ordered that way. For those the actor pages without a fixed order and says so in the log, and rows added during a long run may be missed or repeated. Use `order` to set your own.
- **Wide datasets.** If a page of rows is too large for one answer, the actor reads fewer rows per request. Use `select` to take fewer columns if it still fails.
- **Counts are the portal's.** Views, downloads and update times are what the portal reports and can lag.
- **Public portals only.** The domain must be a public https portal name. IP addresses, local names and portals that need a login are refused.
- **Search is Socrata's.** Which datasets match, and their order for `relevance`, are decided by the Socrata catalog. A portal missing from the catalog still works for rows when you give its domain and dataset ID.

### FAQ

**How much does it cost to read 10,000 rows?**
$10, plus $0.001 for each run. Searching 10,000 datasets costs the same.

**Do I pay for compute or proxy on top?**
No. Platform usage is included in the $1 per 1,000 price. The portals' public APIs are read directly, so no proxy is used.

**Where does the data come from?**
Dataset search reads the public Socrata catalog (Discovery API). Rows come from the SODA API of the portal you name. No key and no login are needed.

**How do I find a dataset ID?**
Run a search first and copy `datasetId` from a result. Or open the dataset page on the portal: the ID is the last part of the address, such as `ydr8-5enu`. You can also paste the full page address into the Portal domain field and the actor takes the domain and ID from it.

**How do I get only new rows?**
Use `where` with a date column, for example `issue_date > '2026-09-01'`, and `order` set to `issue_date DESC`. Put the date of your last run in the filter.

**How do I count rows by category?**
Set `select` to `category, count(*) as total` and `group` to `category`, using a real column name. Each group is one result.

**Can I search across all portals?**
Yes. Leave the domain empty and give search words. Each result shows which portal it comes from.

**Which portals work?**
Any portal that runs Socrata, including most US city, county and state portals and many federal agencies. Portals hosted in Europe are in the EU catalog: set Catalog region to `eu`.

**Is it legal?**
The actor reads public data only, with no login. Open data portals publish under their own terms and licenses. Follow the terms of each portal and the law where you live, and check the license of a dataset before you reuse it.

**Is this an official Socrata product?**
No. It is an independent tool and is not affiliated with or endorsed by Socrata, Tyler Technologies or any portal owner.

**Do I need an Apify account?**
Yes. Actors run from an Apify account, and a free account is enough to start: it includes $5 of platform usage every month. You can [sign up here](https://www.apify.com?fpr=ymnoit). This is a referral link and it costs you nothing.

**Is there a limit on the free plan?**
Yes. A run started from a free plan account delivers the first 10 results, then ends with a message and a link to the plans. Any paid plan returns everything you ask for, up to your own limit. The price per result is the same on every plan.

### More from The One Dollar Store

Every actor here costs $1 per 1,000 results, platform usage included. See the whole store: https://apify.com/one_dollar_store

**Open data and statistics**

- [Eurostat Scraper](https://apify.com/one_dollar_store/eurostat-statistics-scraper): EU statistics tables as rows.
- [Internet Archive Scraper](https://apify.com/one_dollar_store/internet-archive-items-scraper): Books, media and web items from archive.org.
- [World Bank Indicators](https://apify.com/one_dollar_store/world-bank-indicators): Country indicators by year.
- [Wikipedia Pageviews](https://apify.com/one_dollar_store/wikipedia-pageviews-stats): Daily and monthly views per article.
- [GDELT Scraper](https://apify.com/one_dollar_store/gdelt-news-events-scraper): Worldwide news articles by theme and tone.

### Changelog

- October 2026: first release.

# Actor input Schema

## `domain` (type: `string`):

The open data portal, for example data.cityofchicago.org or data.ny.gov. To search for datasets it is optional: leave it empty to search all portals. To read rows it is required. You can also paste the address of a dataset page here and the dataset ID is taken from it.

## `datasetId` (type: `string`):

Fill this to get the rows of one dataset, for example ydr8-5enu. It is the last part of the dataset page address, four characters, a dash and four characters. Leave it empty to search for datasets instead.

## `searchQuery` (type: `string`):

Words to look for in dataset names, descriptions and column names, for example building permits or 311 requests. Used when no dataset ID is given.

## `assetType` (type: `string`):

Datasets are tables of rows. The other kinds are maps, charts, files, external links and stories published on the portal.

## `category` (type: `string`):

Optional. Only datasets in this category, spelled as the portal spells it, for example Public Safety or Transportation.

## `tags` (type: `array`):

Optional. Only datasets that carry all of these tags, one per line.

## `sortBy` (type: `string`):

Order of the datasets when you search.

## `region` (type: `string`):

Where Socrata lists the portal. Almost all portals, including US cities, states and agencies, are in the US catalog. Portals hosted in Europe are in the EU catalog.

## `where` (type: `string`):

Used when reading rows. A SoQL condition, for example issue_date > '2026-01-01'. Column names are the field names shown in the dataset search results.

## `select` (type: `string`):

Used when reading rows. Comma separated column names, for example id, issue_date, street_name. Leave empty for all columns. Functions such as count(\*) work together with Group by.

## `group` (type: `string`):

Used when reading rows. Column names to group by, for example community_area. Use it with a count or sum in Columns to return.

## `order` (type: `string`):

Used when reading rows. For example issue_date DESC. Leave empty to keep the portal's own row order.

## `rowSearchText` (type: `string`):

Used when reading rows. Keeps rows where any text column contains these words (the portal's full text search).

## `appToken` (type: `string`):

Not needed at low volume. Portals throttle anonymous requests more strictly. If a run reports throttling, paste a free app token from the portal's developer settings here.

## `maxItems` (type: `integer`):

The run stops after this many results (datasets or rows). Minimum 10, maximum 10,000.

## Actor input object example

```json
{
  "domain": "data.cityofchicago.org",
  "searchQuery": "building permits",
  "assetType": "dataset",
  "sortBy": "relevance",
  "region": "us",
  "maxItems": 50
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "domain": "data.cityofchicago.org",
    "searchQuery": "building permits",
    "maxItems": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("one_dollar_store/socrata-open-data-search").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "domain": "data.cityofchicago.org",
    "searchQuery": "building permits",
    "maxItems": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("one_dollar_store/socrata-open-data-search").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "domain": "data.cityofchicago.org",
  "searchQuery": "building permits",
  "maxItems": 50
}' |
apify call one_dollar_store/socrata-open-data-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,one_dollar_store/socrata-open-data-search"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1sOpFaaHdkzF67lYj/builds/WFOGlqxRfL3zbhkGN/openapi.json