# Geo Availability Checker (`the_voyager/geo-availability-checker`) Actor

Checks whether a set of URLs are reachable, blocked, or redirected when accessed from specific countries, using residential proxies.
Each check is an action — it runs, logs a pass/fail line to the run log, and charges for having happened. That's the whole output.

- **URL**: https://apify.com/the\_voyager/geo-availability-checker.md
- **Developed by:** [Hassan ali](https://apify.com/the_voyager) (community)
- **Categories:** SEO tools, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 75.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 check-performeds

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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Geo-Availability Checker

Checks whether a set of URLs are reachable, blocked, or redirected when accessed
from specific countries, using residential proxies.

**No dataset output.** This Actor doesn't scrape or return page content, and
there's nothing to download as JSON/CSV. Each check is an action — it runs,
logs a pass/fail line to the run log, and charges for having happened. That's
the whole output.

### Input

```json
{
  "urls": ["https://apify.com"],
  "countries": ["US"],
  "expectedOutcome": "reachable",
  "timeoutSecs": 20,
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

`urls: ["https://apify.com"]` and `countries: ["US"]` are the schema defaults, so this is also what
Apify's automated daily test run will use — keep them pointed at something that will reliably
resolve. Every `url` is combined with
every `country` unless you use the advanced `checks` field to list exact
`{url, country, expected}` triples yourself (useful when different URLs need
different expected outcomes).

`expectedOutcome` can be `"reachable"`, `"blocked"`, or `"any"` (just record
what happened, no pass/fail judgment).

### Setting up monetization (do this in Apify Console, not in code)

1. Actor page → **Publication** tab → **Monetization** section.
2. Choose **Pay per event (PPE)**.
3. Define one custom event named exactly `check-performed`, matching the
   `eventName` used in `src/main.js`. Suggested starting price: **$0.02**
   per check (raw infra cost for a plain HTTP fetch through residential
   proxy runs roughly $0.004-$0.007 per check, so this leaves a healthy
   margin — revisit after real runs via Insights → Monetization).
4. Leave Pay-per-usage/Rental off — PPE is the only model that pays you here.
5. Fill in billing details and identity verification so payouts can process.
6. Set your payout method to PayPal if you expect to be below the $100 wire
   transfer minimum for a while — PayPal's floor is $20.

### Why no headless browser

This uses `got-scraping` (plain HTTP requests with proxy + header/TLS
fingerprint handling) instead of Playwright/Puppeteer. Most availability/
geo-block checks don't need JS execution, and skipping the browser keeps
Compute Unit usage — and therefore your infra-cost deduction — low, which is
what protects your margin on cheap, high-volume runs.

### Local development

```bash
npm install
apify run
```

Requires the [Apify CLI](https://docs.apify.com/cli) and an Apify account
(free plan is enough to build and test) so `Actor.createProxyConfiguration()`
and `Actor.charge()` have something to talk to.

# Actor input Schema

## `checks` (type: `array`):

Optional. Exact list of {"url": "...", "country": "US", "expected": "reachable"} objects to run. If provided, this takes priority over urls + countries below.

## `urls` (type: `array`):

List of URLs to check. Combined with every country below (every URL x every country) unless "checks" is set above.

## `countries` (type: `array`):

Two-letter country codes (e.g. US, GB, FR, BR, JP) to route residential proxy traffic through for each URL.

## `expectedOutcome` (type: `string`):

What counts as a pass for the urls x countries combinations above. Ignored for any entry in "checks" that sets its own "expected".

## `timeoutSecs` (type: `integer`):

Per-check timeout before it's marked unreachable.

## `maxConcurrency` (type: `integer`):

How many checks to run in parallel.

## `proxyConfiguration` (type: `object`):

Choose which residential proxy groups to use. The country for each check comes from "countries" / "checks" above, not from this field.

## Actor input object example

```json
{
  "checks": [],
  "urls": [
    "https://apify.com"
  ],
  "countries": [
    "US"
  ],
  "expectedOutcome": "any",
  "timeoutSecs": 20,
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

One dataset item per completed URL × country check.

# 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("the_voyager/geo-availability-checker").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("the_voyager/geo-availability-checker").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 '{}' |
apify call the_voyager/geo-availability-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,the_voyager/geo-availability-checker"
        }
    }
}

```

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/uKNOv312xZbmOxn8t/builds/G8D5PgJWMOmhfseEh/openapi.json