Maton

Brave Search

Access the Brave Search API with managed authentication. Search the web, images, news, and videos with a privacy-focused search engine.

Reference

GET /brave-search/res/v1/web/search?q={query}

Required Parameters:

  • q (string): Search query (1-400 characters, max 50 words)

Optional Parameters:

  • country (string): 2-letter country code (default: "US")
  • search_lang (string): Search language code (default: "en")
  • ui_lang (string): UI language in RFC 9110 format (default: "en-US")
  • count (integer): Results per page, 1-20 (default: 20)
  • offset (integer): Page offset, 0-9 (default: 0)
  • safesearch (string): Filter level - "off", "moderate", "strict" (default: "moderate")
  • freshness (string): Time filter - "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year), or date range
  • text_decorations (boolean): Include highlighting markers (default: true)
  • result_filter (string): Comma-separated result types (discussions, faq, infobox, news, videos, web)
  • extra_snippets (boolean): Get up to 5 alternative excerpts
  • summary (boolean): Enable summarizer

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/web/search?q=machine+learning&count=10&freshness=pw')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "search",
  "query": {
    "original": "machine learning",
    "show_strict_warning": false,
    "is_navigational": false,
    "country": "us",
    "more_results_available": true
  },
  "web": {
    "type": "search",
    "results": [
      {
        "title": "Machine Learning - Wikipedia",
        "url": "https://en.wikipedia.org/wiki/Machine_learning",
        "description": "Machine learning is a subset of artificial intelligence...",
        "language": "en",
        "family_friendly": true
      }
    ]
  },
  "discussions": {...},
  "faq": {...},
  "videos": {...}
}
GET /brave-search/res/v1/images/search?q={query}

Required Parameters:

  • q (string): Search query

Optional Parameters:

  • country (string): 2-letter country code
  • search_lang (string): Search language code
  • count (integer): Results per page, 1-20
  • safesearch (string): Filter level - "off", "moderate", "strict"

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/images/search?q=sunset&count=5')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "images",
  "results": [
    {
      "title": "Beautiful Sunset",
      "url": "https://example.com/sunset.jpg",
      "source": "https://example.com/gallery",
      "thumbnail": {
        "src": "https://imgs.search.brave.com/..."
      },
      "properties": {
        "width": 1920,
        "height": 1080,
        "format": "jpeg"
      }
    }
  ]
}
GET /brave-search/res/v1/news/search?q={query}

Required Parameters:

  • q (string): Search query

Optional Parameters:

  • country (string): 2-letter country code
  • search_lang (string): Search language code
  • count (integer): Results per page, 1-20
  • freshness (string): Time filter - "pd", "pw", "pm", "py"
  • safesearch (string): Filter level

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/news/search?q=technology&count=5&freshness=pd')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "news",
  "results": [
    {
      "title": "Latest Tech News",
      "url": "https://example.com/news/tech",
      "description": "Breaking technology news...",
      "age": "2 hours ago",
      "source": {
        "name": "Tech News",
        "url": "https://technews.com"
      },
      "thumbnail": {
        "src": "https://imgs.search.brave.com/..."
      }
    }
  ]
}
GET /brave-search/res/v1/videos/search?q={query}

Required Parameters:

  • q (string): Search query

Optional Parameters:

  • country (string): 2-letter country code
  • search_lang (string): Search language code
  • count (integer): Results per page, 1-20
  • safesearch (string): Filter level

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/videos/search?q=tutorial&count=5')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "videos",
  "results": [
    {
      "title": "Python Tutorial for Beginners",
      "url": "https://www.youtube.com/watch?v=...",
      "description": "Learn Python programming...",
      "age": "1 year ago",
      "duration": "3:45:00",
      "thumbnail": {
        "src": "https://imgs.search.brave.com/..."
      },
      "meta_url": {
        "hostname": "www.youtube.com"
      }
    }
  ]
}

Local POIs

GET /brave-search/res/v1/local/pois?ids={poi_ids}

Get details about local points of interest by their IDs (obtained from web search results).

Required Parameters:

  • ids (string): Comma-separated POI IDs

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/local/pois?ids=poi_123,poi_456')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "local_pois",
  "results": [
    {
      "id": "poi_123",
      "name": "Coffee Shop",
      "address": "123 Main St",
      "phone": "+1-555-1234",
      "rating": 4.5,
      "reviews": 128
    }
  ]
}

POI Descriptions

GET /brave-search/res/v1/local/descriptions?ids={poi_ids}

Get detailed descriptions for local points of interest.

Required Parameters:

  • ids (string): Comma-separated POI IDs

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/local/descriptions?ids=poi_123')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "local_descriptions",
  "results": [
    {
      "id": "poi_123",
      "description": "A cozy coffee shop known for artisanal brews..."
    }
  ]
}

Autosuggest

Note: Requires Autosuggest subscription plan.

GET /brave-search/res/v1/suggest/search?q={query}

Get search suggestions as users type.

Required Parameters:

  • q (string): Partial search query

Optional Parameters:

  • country (string): 2-letter country code
  • count (integer): Number of suggestions to return
  • rich (boolean): Enable enhanced metadata

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/suggest/search?q=how+to&count=5&rich=true')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "suggest",
  "query": {
    "original": "how to"
  },
  "results": [
    {
      "query": "how to learn python",
      "is_entity": false
    },
    {
      "query": "how to code",
      "is_entity": false
    }
  ]
}

Spellcheck

Note: Requires Spellcheck subscription plan.

GET /brave-search/res/v1/spellcheck/search?q={query}

Check spelling and get corrections.

Required Parameters:

  • q (string): Query to check for spelling errors
  • country (string): Country code for localized corrections

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/spellcheck/search?q=helo+wrold&country=US')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "type": "spellcheck",
  "query": {
    "original": "helo wrold"
  },
  "results": [
    {
      "query": "hello world"
    }
  ]
}

Note: Requires Summarizer subscription plan.

First, perform a web search with summary=1 to get a summarizer key, then use that key to fetch the summary.

Get Summarizer Key

GET /brave-search/res/v1/web/search?q={query}&summary=1

Fetch Summary

GET /brave-search/res/v1/summarizer/search?key={summarizer_key}

Optional Parameters:

  • entity_info (boolean): Include entity details
  • inline_references (boolean): Include citation markers

Example:

python <<'EOF'
import urllib.request, os, json

# Step 1: Get summarizer key from web search
req = urllib.request.Request('https://api.maton.ai/brave-search/res/v1/web/search?q=what+is+python&summary=1')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
data = json.load(urllib.request.urlopen(req))
summarizer_key = data.get('summarizer', {}).get('key')

# Step 2: Fetch summary using the key
if summarizer_key:
    req = urllib.request.Request(f'https://api.maton.ai/brave-search/res/v1/summarizer/search?key={summarizer_key}')
    req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
    print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Additional Summarizer Endpoints

GET /brave-search/res/v1/summarizer/summary?key={key}           # Summary only
GET /brave-search/res/v1/summarizer/title?key={key}             # Title only
GET /brave-search/res/v1/summarizer/enrichments?key={key}       # Enrichment data
GET /brave-search/res/v1/summarizer/followups?key={key}         # Follow-up suggestions
GET /brave-search/res/v1/summarizer/entity_info?key={key}       # Entity information

Resources

PreviousBoxNextBrevo

On this page

Reference
Web Search
Image Search
News Search
Video Search
Local POIs
POI Descriptions
Autosuggest
Spellcheck
Get Summarizer Key
Fetch Summary
Additional Summarizer Endpoints
Resources