Map API

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.

Endpoint

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

Quickstart

cURL
Javascript
Python

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"
}'

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();

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
Javascript
Python

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
}'

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();

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
Javascript
Python

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"
}'

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();

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
Javascript
Python

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"
  }
}'

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();

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
Javascript
Python

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
}'

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();

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.

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.

Quickstart​

Search relevance​

Sitemap control​

Geo-targeting​

Filtering options​

Request body​

Response fields​

Configuration options​