API v1

An API, and an MCP server

Launch extractions from your scripts, feed your CRM automatically, or let an AI assistant query your prospect database directly.

Create an account See plans

Authentication

Every request requires an API key, generated from your workspace.

Header

Authorization: Bearer msk_live_YOUR_KEY

API access is included from the Pro plan. Rate limits are 120 requests/minute requests/minute on Pro and 600 requests/minute requests/minute on Scale. Every response carries the X-RateLimit-*headers.

Endpoints

POST/api/v1/search

Launches a search. With `wait: true`, returns the results directly.

GET/api/v1/search

Lists the organisation's searches.

GET/api/v1/search/{id}

Status, progress and statistics for one search.

GET/api/v1/search/{id}/results

Paginated results, with filters as URL parameters.

DELETE/api/v1/search/{id}

Deletes a search and its results.

GET/api/v1/categories

Taxonomy of 370 categories and the geographic reference data.

GET/api/v1/me

Organisation, plan, remaining quota and rate limits.

Full example

Find every plumber in Lyon with no website but whose email we have.

Request

curl -X POST https://mysearch.gg/api/v1/search \
  -H "Authorization: Bearer msk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "plumber",
    "location": "Lyon, France",
    "filters": { "website": "no", "email": "yes" },
    "limit": 500,
    "wait": true
  }'

Response

{
  "search_id": "8f3c…",
  "status": "completed",
  "location": "Lyon",
  "stats": {
    "total": 412,
    "with_email": 251,
    "without_website": 198,
    "average_score": 71
  },
  "places": [
    {
      "place_id": "ChIJ…",
      "name": "Plomberie Mercier & Fils",
      "address": { "city": "Lyon", "postal_code": "69003" },
      "phone": "+33478000000",
      "emails": [
        { "email": "contact@…", "source": "website_mailto", "confidence": 92 }
      ],
      "website": null,
      "rating": 4.8,
      "review_count": 127,
      "score": {
        "value": 92,
        "grade": "A",
        "signals": [
          { "key": "no_website", "kind": "opportunity", "label": "No website" }
        ]
      }
    }
  ]
}

Available filters

In the request body for POST /search, as URL parameters for GET /results.

Filter	Values	Effect
website	yes / no	Has a website, or not
email	yes / no	An email was found
phone	yes / no	A phone number is present
mobile	yes / no	The number is a mobile
claimed	yes / no	The Google listing is claimed
facebook / instagram / linkedin	yes / no	Present on that network
rating_min / rating_max	0 – 5	Rating bounds
reviews_min / reviews_max	integer	Review-count bounds
score_min	0 – 100	Minimum lead score

MCP server

Plug Claude, ChatGPT or Gemini straight into mySearch. The assistant launches searches and reasons over the results without going through an export.

MCP client configuration

{
  "mcpServers": {
    "mysearch": {
      "type": "http",
      "url": "https://mysearch.gg/api/mcp",
      "headers": { "Authorization": "Bearer msk_live_YOUR_KEY" }
    }
  }
}

Exposed tools

search_places— launches a search and returns the enriched results
get_results— walks through a search's results with filters
list_searches— lists searches and their status
market_stats— aggregated read on a market: digital maturity, lead quality
list_categories— explores the category taxonomy

Example question for a connected assistant: “How many restaurants in Bordeaux have no website? Give me the twenty with the most reviews.”

Error codes

401missing_api_key / invalid_api_keyKey missing, invalid or revoked

402quota_exceededLead quota exhausted for the cycle

403plan_requiredFeature not included in the plan

404not_foundResource not found

422invalid_requestMissing or invalid parameters

429rate_limit_exceeded / too_many_jobsToo many requests or concurrent searches

503engine_unavailableExtraction engine temporarily unavailable

A question about integrating? See the plans with API access