# Sitemap Image Extractor (`stellar_ballet_0bu/sitemap-image-extractor`) Actor

Parse any public sitemap.xml (or sitemap index) and extract every <image:image> extension entry. Emits one row per (URL, image) with loc, title, caption, geo\_location, license.

- **URL**: https://apify.com/stellar\_ballet\_0bu/sitemap-image-extractor.md
- **Developed by:** [Nikita S](https://apify.com/stellar_ballet_0bu) (community)
- **Categories:** Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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

## Sitemap Image Extractor (image:image namespace)

Parse any public `sitemap.xml` (or sitemap index) and emit one dataset row per `<image:image>` extension entry with `loc`, `title`, `caption`, `geo_location`, `license`. Sitemap-index BFS-followed up to `maxSitemaps` (default 25, max 100). Pairs with the public `sitemap-delta-monitor` and `sitemap-lastmod-window` Actors.

- **Inputs**: `sitemapUrl` (public sitemap URL) **or** `xmlText` (inline sitemap XML), `maxSitemaps` (BFS cap, default 25, max 100), `timeoutSec` (per-fetch, default 20, max 120).
- **Per-row output**:
  - `_kind: "image"` — one row per `<image:image>` block found, with `pageUrl`, `image` (the image's own `loc`), `title`, `caption`, `geoLocation`, `license`, and `sourceSitemap`.
- **Output** (`SUMMARY`): `ok`, `sitemapsFetched`, `urlsScanned`, `imagesFound`, `totalRows`.

### Quick start

```bash
apify call stellar_ballet_0bu/sitemap-image-extractor -i '{
  "sitemapUrl": "https://www.google.com/sitemap.xml",
  "maxSitemaps": 5
}'
````

The default dataset will have one item per `<image:image>` entry found across the sitemaps. `SUMMARY.imagesFound` returns the total image count.

### Inputs

- `sitemapUrl` — public URL of a `sitemap.xml` or sitemap index. Used only if `xmlText` is empty.
- `xmlText` — inline sitemap XML string. Useful for offline test fixtures and crawlers that have the XML in hand.
- `maxSitemaps` — BFS cap on how many child sitemaps to follow from a sitemap index. Default 25, max 100.
- `timeoutSec` — per-fetch timeout in seconds. Default 20, max 120.

### Use cases

- **Image SEO audit**: count and surface every image declared in a publisher's sitemap (Google Image Search, Bing Image Search).
- **Content migration QA**: confirm the new site still declares the same set of image URLs as the old site.
- **Asset license compliance**: pull the `license` field for every image declared in the sitemap.
- **News/publisher inventory**: build a CSV/JSON view of all images the publisher has indexed in their sitemap.
- **RAG image indexing**: produce a clean list of image URLs for downstream image-to-text or visual embedding pipelines.

### API notes

- Pure XML parser + simple HTTP fetcher. No browser, no JS execution, no anti-bot circumvention. Public URLs only.
- Sitemap-index BFS: if the root sitemap is an index, the Actor fetches up to `maxSitemaps` child sitemaps and merges their `<image:image>` entries into the same output stream.
- Attribute namespace is handled — `<image:image>` with the `xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"` namespace is the standard.
- Both `xmlText` and `sitemapUrl` work; if both are set, `xmlText` wins.
- XML entities (`&amp;`, `&lt;`, etc.) are decoded.
- Fetch failures are recorded as `_kind: "image"` rows with `error: "fetch failed: ..."` and a `null` image — these are NOT counted in `imagesFound`.

### Pricing (Pay per event)

| Event | Description | USD |
|---|---|---|
| `apify-actor-start` | Built-in start charge, per Apify platform usage | per pricing tier |
| `image_extracted` | One charge per `<image:image>` block actually emitted. Fetch-error rows and zero-image sitemaps cost nothing. | $0.0001 |

`currentPricingInfo` activates on `2026-07-22T00:00:00Z`. The Actor's code calls `Actor.charge({ eventName: 'image_extracted', count: imagesFound })` only for actually-emitted image rows.

### Cost expectations

A typical news publisher's sitemap with 50k URLs and 30k image entries will cost roughly $3 of usage credits on top of the standard start charge. Use `maxSitemaps` to cap the BFS depth if you only need a sample.

### FAQ

**Does it follow robots.txt?** No — the Actor is a sitemap parser, not a crawler. It will fetch whatever URL you give it, up to `maxSitemaps` children. Use `maxSitemaps` to scope BFS for large publisher sites.

**What about `<image:thumbnail>` or other image extensions?** Only the `image:image` namespace is supported (the Google/Bing sitemap-image extension). Other extensions are ignored.

**Does it work with `robots.txt`-discovered sitemaps?** Pass the sitemap URL directly. If you have multiple sitemaps, run the Actor N times or chain via a wrapper.

**Why are some rows missing `title`/`caption`/`license`?** Those are optional fields in the spec. The Actor emits `null` for missing fields, never synthesised values.

**What happens with non-XML responses?** The parser will produce zero image rows and log a `parse failed: ...` row. Check `SUMMARY.urlsScanned` — if it's 0, the URL probably wasn't a sitemap.

**Can I get a JSON list of unique image URLs only?** No — the Actor emits one row per (URL, image) pair. Run the dataset through `csv-dedupe-normalizer` to dedupe by the `image` column.

### Limits

- BFS capped at `maxSitemaps` (default 25, max 100). For very large publishers with thousands of child sitemaps, run multiple invocations.
- Per-fetch `timeoutSec` (default 20, max 120) — long-running fetches will be aborted.
- XML only — sitemap.txt, RSS, Atom, RDF are not supported.

### Related Actors

- `sitemap-delta-monitor` (public) — sitemap URL deltas, before/after, lastmod changes
- `sitemap-lastmod-window` — filter any sitemap by `<lastmod>` date window
- `sitemap-news-sitemap-extractor` — Google News sitemap parser (`<news:news>` namespace)
- `sitemap-priority-changefreq-analyzer` — `<priority>` and `<changefreq>` distribution analysis
- `robots-sitemap-feed-discovery` — discover sitemaps and feeds from `robots.txt`
- `product-feed-delta-monitor` — for product/feed deltas, not sitemaps

### Support

- Source: hidden (paid Actor pattern; not exposed by default).
- Issues / feature requests: open a thread on the public Apify Store Actor page (button on the right of the Store listing) or message the maintainer through the Apify Console.
- For paid-pilot bulk runs (large publisher audits, scheduled re-runs, custom output formats), contact the maintainer via the Apify Console.

### License

MIT-style Apify Actor Source-Available License. You may use the public Actor output and integrate the public results; you may not re-host the Actor source or re-publish it as a competing Actor.

# Actor input Schema

## `sitemapUrl` (type: `string`):

Public sitemap.xml or sitemap-index URL.

## `xmlText` (type: `string`):

Inline sitemap XML. Used if sitemapUrl is empty.

## `maxSitemaps` (type: `integer`):

For sitemap-index inputs, the maximum number of leaf sitemaps to fetch and parse.

## `timeoutSec` (type: `integer`):

Per-fetch request timeout in seconds.

## Actor input object example

```json
{
  "sitemapUrl": "",
  "xmlText": "",
  "maxSitemaps": 25,
  "timeoutSec": 20
}
```

# Actor output Schema

## `rows` (type: `string`):

Per-(pageUrl, image) row with loc, title, caption, geoLocation, license, sourceSitemap.

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

Run summary with sitemaps fetched, urls scanned, images found.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("stellar_ballet_0bu/sitemap-image-extractor").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("stellar_ballet_0bu/sitemap-image-extractor").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 '{}' |
apify call stellar_ballet_0bu/sitemap-image-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=stellar_ballet_0bu/sitemap-image-extractor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Sitemap Image Extractor",
        "description": "Parse any public sitemap.xml (or sitemap index) and extract every <image:image> extension entry. Emits one row per (URL, image) with loc, title, caption, geo_location, license.",
        "version": "0.2",
        "x-build-id": "tnNnozGUrEuUghABB"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/stellar_ballet_0bu~sitemap-image-extractor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-stellar_ballet_0bu-sitemap-image-extractor",
                "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/stellar_ballet_0bu~sitemap-image-extractor/runs": {
            "post": {
                "operationId": "runs-sync-stellar_ballet_0bu-sitemap-image-extractor",
                "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/stellar_ballet_0bu~sitemap-image-extractor/run-sync": {
            "post": {
                "operationId": "run-sync-stellar_ballet_0bu-sitemap-image-extractor",
                "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",
                "properties": {
                    "sitemapUrl": {
                        "title": "Sitemap URL",
                        "type": "string",
                        "description": "Public sitemap.xml or sitemap-index URL.",
                        "default": ""
                    },
                    "xmlText": {
                        "title": "Inline XML (optional)",
                        "type": "string",
                        "description": "Inline sitemap XML. Used if sitemapUrl is empty.",
                        "default": ""
                    },
                    "maxSitemaps": {
                        "title": "Max sitemap leaves to follow",
                        "type": "integer",
                        "description": "For sitemap-index inputs, the maximum number of leaf sitemaps to fetch and parse.",
                        "default": 25
                    },
                    "timeoutSec": {
                        "title": "Timeout per fetch (sec)",
                        "type": "integer",
                        "description": "Per-fetch request timeout in seconds.",
                        "default": 20
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```