Map API

The Map API is only available for Cloud plans. Contact us for more information here.

Discover all URLs on a website. Send a base URL and receive a deduplicated list of pages with optional titles and descriptions. Use the search parameter to rank results by relevance, and sitemap to control whether discovery uses the site's XML sitemap, on-page links, or both. To search the open web rather than a single site, see the Search API. For extracting page content from discovered URLs, use the Smart Scrape API.

Endpoint

• Method: POST
• Path: /map
• Auth: token query parameter (?token=)
• Content-Type: application/json
• Response: application/json

Prerequisites

• A Browserless API token from your account dashboard

Quickstart

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/map?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://www.browserless.io"
}'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/map?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/json"
};

const data = {
  url: "https://www.browserless.io"
};

const mapSite = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const result = await response.json();
  console.log(result);
};

mapSite();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/map?token={TOKEN}"
headers = {
    "Content-Type": "application/json"
}

data = {
    "url": "https://www.browserless.io"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result)

Response

{
  "success": true,
  "links": [
    {
      "url": "https://www.browserless.io",
      "title": "Browserless - Headless Browser Automation",
      "description": "Headless browser automation, without the hosting headaches."
    },
    {
      "url": "https://www.browserless.io/pricing",
      "title": "Pricing",
      "description": "Simple, transparent pricing for headless browser automation."
    },
    {
      "url": "https://www.browserless.io/blog",
      "title": "Blog",
      "description": "Insights, tips, and updates on headless browser automation."
    }
    // ...more URLs up to the specified limit
  ]
}

Search relevance

Use the search parameter to order results by relevance to a query. This is useful when you only need URLs related to a specific topic from a large site.

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/map?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://www.browserless.io",
  "search": "pricing",
  "limit": 10
}'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/map?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/json"
};

const data = {
  url: "https://www.browserless.io",
  search: "pricing",
  limit: 10
};

const mapSite = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const result = await response.json();
  console.log(result);
};

mapSite();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/map?token={TOKEN}"
headers = {
    "Content-Type": "application/json"
}

data = {
    "url": "https://www.browserless.io",
    "search": "pricing",
    "limit": 10
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result)

Response

{
  "success": true,
  "links": [
    {
      "url": "https://www.browserless.io/pricing",
      "title": "Pricing",
      "description": "Simple, transparent pricing for headless browser automation."
    },
    {
      "url": "https://www.browserless.io/blog/pricing-update"
    }
    // URLs ordered by relevance to "pricing"
  ]
}

Sitemap control

The sitemap parameter controls how the API uses sitemaps for URL discovery:

Mode	Description
"include"	(default) Uses both sitemap and on-page links for discovery.
"skip"	Ignores the sitemap. Only discovers URLs found on the page itself.
"only"	Returns only URLs listed in the sitemap.

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/map?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://www.browserless.io",
  "sitemap": "only"
}'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/map?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/json"
};

const data = {
  url: "https://www.browserless.io",
  sitemap: "only"
};

const mapSite = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const result = await response.json();
  console.log(result);
};

mapSite();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/map?token={TOKEN}"
headers = {
    "Content-Type": "application/json"
}

data = {
    "url": "https://www.browserless.io",
    "sitemap": "only"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result)

Geo-targeting

Use the location parameter to route requests through a proxy in a specific country. This is useful for discovering region-specific URLs or bypassing geographic restrictions.

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/map?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com",
  "location": {
    "country": "gb"
  }
}'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/map?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/json"
};

const data = {
  url: "https://example.com",
  location: {
    country: "gb"
  }
};

const mapSite = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const result = await response.json();
  console.log(result);
};

mapSite();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/map?token={TOKEN}"
headers = {
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com",
    "location": {
        "country": "gb"
    }
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result)

Filtering options

Control which URLs are included in results:

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/map?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://www.browserless.io",
  "limit": 100,
  "includeSubdomains": false,
  "ignoreQueryParameters": true
}'

Javascript

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/map?token=${TOKEN}`;
const headers = {
  "Content-Type": "application/json"
};

const data = {
  url: "https://www.browserless.io",
  limit: 100,
  includeSubdomains: false,
  ignoreQueryParameters: true
};

const mapSite = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const result = await response.json();
  console.log(result);
};

mapSite();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/map?token={TOKEN}"
headers = {
    "Content-Type": "application/json"
}

data = {
    "url": "https://www.browserless.io",
    "limit": 100,
    "includeSubdomains": False,
    "ignoreQueryParameters": True
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result)

Request body

Field	Type	Required	Default	Description
url	string	Yes	—	The base URL to discover links from. Must be http:// or https://.
search	string	No	—	Search query to order results by relevance.
limit	number	No	5000	Maximum number of URLs to return. Must be between 1 and 5000.
timeout	number	No	Server default	Request timeout in milliseconds. Capped at the server-configured maximum.
sitemap	string	No	"include"	Sitemap behavior: "include", "skip", or "only".
includeSubdomains	boolean	No	true	Whether to include URLs from subdomains of the base URL.
ignoreQueryParameters	boolean	No	true	Exclude query parameters from discovered URLs, reducing duplicates.
location	object	No	—	Geo-targeting settings. See below.
location.country	string	No	"us"	Country code for proxy routing (e.g., "us", "gb", "de").
location.languages	string[]	No	—	Preferred languages for the request.
proxy	string	No	"residential"	Proxy network to route through: "residential" (6 units/MB) or "datacenter" (2 units/MB).

Response fields

Field	Type	Description
success	boolean	Whether the mapping operation succeeded.
links	MapLink[]	Array of discovered URLs with optional metadata.
links[].url	string	The discovered URL.
links[].title	string | undefined	Page title, when available.
links[].description	string | undefined	Page description, when available.

Configuration options

The /map API supports a timeout query parameter to control the maximum time allowed for the mapping operation:

POST /map?token=YOUR_API_TOKEN_HERE&timeout=30000

The timeout value is in milliseconds. If not specified, the server default timeout is used.

FAQ & Troubleshooting

Why am I getting a 401 Unauthorized error?

Your API token is missing or invalid. Include it as a ?token= query parameter or in the Authorization header. Verify the token in your account dashboard.

My request returns an empty response

The page may not have finished loading. Increase waitForTimeout or use waitForSelector to wait for specific content before extracting data.

Next steps

REST API overview

introduction to all available endpoints

API playground

test endpoints interactively