# Google Street View - Semantic Search (`bfarrington/streetview-semantic-search`) Actor

AI-powered Google Street View search: scan every panorama around a location and get images ranked by how well they match your text prompt. Find storefronts, construction, murals, terraces — anything visible from the street. No API key needed.

- **URL**: https://apify.com/bfarrington/streetview-semantic-search.md
- **Developed by:** [Ben Farrington](https://apify.com/bfarrington) (community)
- **Categories:** AI, Real estate, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 geo-tagged images

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Street View Semantic Search — find anything in Google Street View with AI

**Search real-world streets with natural language.** Give this actor a location, a radius, and a plain-English prompt — it scans every Google Street View panorama in the area and scores each image on how well it matches your prompt, using CLIP AI image understanding. Results stream into your dataset live as the scan progresses.

No API keys, no setup, no scraping infrastructure. Type what you're looking for and get scored, geotagged street imagery back in minutes.

````

"red storefront"        → every shopfront in the area, reddest first
"outdoor cafe seating"  → pavement terraces, ranked
"construction site"     → active building works with coordinates
"street art mural"      → murals and graffiti walls, scored

````

### What can you find?

- 🏪 **Retail & real estate** — storefronts, vacant units, for-sale signs, building conditions
- 🏗️ **Construction & infrastructure** — scaffolding, roadworks, cranes, utility works
- 🌳 **Urban planning & environment** — green spaces, bike lanes, street furniture, accessibility ramps
- 📸 **Location scouting** — film/photo backdrops: "cobblestone alley", "neon signs at dusk"
- 🚗 **Mobility & parking** — EV chargers, parking lots, bus stops, loading bays
- 🎯 **Lead generation** — restaurants with terraces, shops with awnings, businesses with billboards

Any question you could answer by walking the streets and looking — this actor answers by looking for you.

### How it works

1. **You provide** a location (address or coordinates), search radius, and a text prompt
2. **Panorama discovery** — the actor sweeps the area and finds every available Street View panorama
3. **Image capture** — it photographs each panorama from multiple compass headings
4. **AI ranking** — a CLIP vision model scores every image against your prompt (semantic matching, not keywords: "place to sit outside" finds benches and terraces)
5. **You receive** every image as a dataset item — streamed live during the run — each with a match rating (`match`, `ambiguous`, or `no_match`), coordinates, capture date, and a download link

### Input

| Field | Default | Description |
|---|---|---|
| `location` | — | Address (`"Camden High Street, London"`) or coordinates (`"51.5033,-0.1196"`) |
| `searchPrompt` | — | What to look for, in plain English |
| `radiusMeters` | 250 | Search radius (10–5000 m) |
| `maxImages` | 400 | Maximum images to capture (= maximum results) |
| `headings` | `[0, 90, 180, 270]` | Camera directions per panorama |
| `newerThan` | — | Only imagery captured after this date, e.g. `"2024-01"` — older panoramas are skipped before download |
| `gridSpacingMeters` | 15 | Discovery density — smaller finds more panoramas |

### Output

One dataset item per image, streamed in as it's captured. Every image carries an AI match rating — `match`, `ambiguous`, or `no_match` — so you can filter straight down to the hits.

```json
{
    "match": "match",
    "panoId": "CAoSF0NJSE0...",
    "lat": 51.50335,
    "lng": -0.11989,
    "heading": 0,
    "date": "2023-06",
    "imageUrl": "https://api.apify.com/v2/key-value-stores/.../result-001-....jpg"
}
````

Export to JSON, CSV, or Excel; images are stored with the run and downloadable via `imageUrl`.

### Why this actor?

- ✅ **Zero setup** — no Google API key, no billing account, no quota management
- ✅ **Semantic search, not keyword search** — CLIP understands concepts, colors, objects, scenes
- ✅ **Complete results** — every scanned image returned with its match rating and location, nothing hidden
- ✅ **Geotagged** — every result carries exact coordinates and Street View capture date
- ✅ **Official imagery** — sourced from the Google Street View API, no fragile scraping

### FAQ

**How many images will I get?**
Up to `maxImages`. A 250 m urban radius typically holds 50–150 panoramas; each is captured from the headings you choose (4 by default).

**Does it work everywhere?**
Anywhere Google Street View has coverage — most cities and roads worldwide. No coverage = zero results, and you're only charged for images produced.

**What do the match ratings mean?**
`match` means the image is a confident visual match for your prompt; `ambiguous` is borderline and worth a look; `no_match` means the image probably doesn't contain what you asked for. Filter the dataset on the `match` field to keep only the levels you want.

**Can I search for multiple things?**
One prompt per run. Kick off parallel runs for multiple prompts over the same area.

**How fresh are the images?**
Each result includes its Street View capture `date` (e.g. `"2023-06"`). Set `newerThan` (e.g. `"2024-01"`) to skip older panoramas entirely — you're only charged for images that pass the filter. Note: areas Google last photographed before your cutoff will return no results.

***

*Street View scraper · semantic image search · CLIP visual search · Google Street View images by location · AI street imagery analysis*

# Actor input Schema

## `location` (type: `string`):

"lat,lng" pair or free-text address (geocoded via Google Geocoding API).

## `searchPrompt` (type: `string`):

Natural-language description of what to find in Street View imagery.

## `radiusMeters` (type: `integer`):

Radius around the location to search for panoramas.

## `maxImages` (type: `integer`):

Hard cap on paid Street View Static API requests (~$7 per 1000).

## `headings` (type: `array`):

Compass headings (degrees) to capture per panorama. Images per panorama = number of headings.

## `newerThan` (type: `string`):

Skip panoramas captured before this date, e.g. "2024-01" or "2024". Filtering happens before download, so you are never charged for older imagery. Leave empty for all dates.

## `gridSpacingMeters` (type: `integer`):

Sampling grid density for panorama discovery (metadata calls are free; smaller = better coverage, more calls).

## `stopAfterMatches` (type: `integer`):

Stop once this many images score a full "match" (not just "ambiguous"). Caps Static API spend when you only need a few confirmed hits rather than every occurrence in the area. 0 disables the limit (scan up to Max images).

## Actor input object example

```json
{
  "location": "51.5033,-0.1196",
  "searchPrompt": "red storefront",
  "radiusMeters": 250,
  "maxImages": 400,
  "headings": [
    0,
    90,
    180,
    270
  ],
  "gridSpacingMeters": 15,
  "stopAfterMatches": 0
}
```

# Actor output Schema

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

No description

## `resultsCsv` (type: `string`):

No description

## `images` (type: `string`):

No description

## `run` (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 = {
    "location": "51.5033,-0.1196",
    "searchPrompt": "red storefront"
};

// Run the Actor and wait for it to finish
const run = await client.actor("bfarrington/streetview-semantic-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 = {
    "location": "51.5033,-0.1196",
    "searchPrompt": "red storefront",
}

# Run the Actor and wait for it to finish
run = client.actor("bfarrington/streetview-semantic-search").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "location": "51.5033,-0.1196",
  "searchPrompt": "red storefront"
}' |
apify call bfarrington/streetview-semantic-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=bfarrington/streetview-semantic-search",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Google Street View - Semantic Search",
        "description": "AI-powered Google Street View search: scan every panorama around a location and get images ranked by how well they match your text prompt. Find storefronts, construction, murals, terraces — anything visible from the street. No API key needed.",
        "version": "0.1",
        "x-build-id": "BHjPCUMYqxeslbGx0"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/bfarrington~streetview-semantic-search/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-bfarrington-streetview-semantic-search",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/bfarrington~streetview-semantic-search/runs": {
            "post": {
                "operationId": "runs-sync-bfarrington-streetview-semantic-search",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/bfarrington~streetview-semantic-search/run-sync": {
            "post": {
                "operationId": "run-sync-bfarrington-streetview-semantic-search",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "location",
                    "searchPrompt"
                ],
                "properties": {
                    "location": {
                        "title": "Location",
                        "type": "string",
                        "description": "\"lat,lng\" pair or free-text address (geocoded via Google Geocoding API)."
                    },
                    "searchPrompt": {
                        "title": "Search prompt",
                        "type": "string",
                        "description": "Natural-language description of what to find in Street View imagery."
                    },
                    "radiusMeters": {
                        "title": "Search radius (m)",
                        "minimum": 10,
                        "maximum": 5000,
                        "type": "integer",
                        "description": "Radius around the location to search for panoramas.",
                        "default": 250
                    },
                    "maxImages": {
                        "title": "Max images (cost cap)",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Hard cap on paid Street View Static API requests (~$7 per 1000).",
                        "default": 400
                    },
                    "headings": {
                        "title": "Camera headings",
                        "type": "array",
                        "description": "Compass headings (degrees) to capture per panorama. Images per panorama = number of headings.",
                        "default": [
                            0,
                            90,
                            180,
                            270
                        ]
                    },
                    "newerThan": {
                        "title": "Only imagery newer than",
                        "pattern": "^\\d{4}(-\\d{2})?$",
                        "type": "string",
                        "description": "Skip panoramas captured before this date, e.g. \"2024-01\" or \"2024\". Filtering happens before download, so you are never charged for older imagery. Leave empty for all dates."
                    },
                    "gridSpacingMeters": {
                        "title": "Grid spacing (m)",
                        "minimum": 5,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Sampling grid density for panorama discovery (metadata calls are free; smaller = better coverage, more calls).",
                        "default": 15
                    },
                    "stopAfterMatches": {
                        "title": "Stop after N matches",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Stop once this many images score a full \"match\" (not just \"ambiguous\"). Caps Static API spend when you only need a few confirmed hits rather than every occurrence in the area. 0 disables the limit (scan up to Max images).",
                        "default": 0
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```