{"openapi":"3.1.0","info":{"title":"gmaps.dev","version":"0.1.0","description":"Create an API key at https://console.gmaps.dev/keys and send it with every call. The guides are at https://gmaps.dev/docs/en.\n\ngmaps.dev is not affiliated with Google or Alphabet."},"servers":[{"url":"https://api.gmaps.dev/v1"}],"tags":[{"name":"Attributions","x-displayName":"Attributions"},{"name":"Places","x-displayName":"Places"},{"name":"Collections","x-displayName":"Collections"},{"name":"Exports","x-displayName":"Exports"},{"name":"Coverage","x-displayName":"Coverage"},{"name":"Usage","x-displayName":"Usage"},{"name":"Webhooks","x-displayName":"Webhooks"}],"paths":{"/attributions":{"get":{"operationId":"get_attributions","tags":["Attributions"],"summary":"List the open-source projects we build on","description":"List the projects credited by gmaps.dev, with their licenses and notices. No API key needed. Costs no credits.","security":[],"responses":{"200":{"description":"List the open-source projects we build on","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A short name for the project that never changes."},"name":{"type":"string","minLength":1,"description":"The project's name."},"url":{"type":"string","format":"uri","description":"The project's home page."},"license":{"type":"string","minLength":1,"description":"Its license, as an SPDX id such as MIT."},"licenseUrl":{"type":"string","format":"uri","description":"Where to read the license."},"usage":{"minItems":1,"type":"array","items":{"type":"string","enum":["data","sidecar","library"]},"description":"How we use it: `data` for data we show, `sidecar` for a service we run beside ours, `library` for code we build with."},"notice":{"type":"string","minLength":1,"description":"The notice its license asks us to show, word for word."}},"required":["id","name","url","license","licenseUrl","usage","notice"],"additionalProperties":false}},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"attributions.list","returns":"AttributionDto[]"},"x-mcp-tool":"get_attributions"}},"/places/search":{"post":{"operationId":"search_places","tags":["Places"],"summary":"Search for places","description":"Find places by what they are and where they are, such as bakeries in Curitiba. Places we saved from earlier searches come back at once, for free. If they do not fill `limit`, a collection starts to find the rest and the answer includes it: each new place costs one credit as it arrives, and it stops at `limit`, so a search never costs more than `limit` credits. Search again later, or read the collection, to get the new ones; with `wait`, the answer waits up to 60 seconds for them. Needs an API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"keywords":{"minItems":1,"type":"array","items":{"type":"string"},"description":"What to search for, such as [\"bakery\"]. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"Where to search. Give exactly one of: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"default":"pt","description":"The language to search in. New places come back in it. Two letters, such as pt or en.","type":"string","pattern":"^[a-z]{2}$"},"minRating":{"default":null,"description":"Keep only places rated at least this, from 1 to 5. Null keeps every place.","anyOf":[{"type":"number","minimum":1,"maximum":5},{"type":"null"}]},"limit":{"default":20,"description":"How many places you want, from 1 to 120. Also the most a search can cost.","type":"integer","minimum":1,"maximum":120},"wait":{"default":0,"description":"Seconds to wait for new places when we have to collect them, up to 60. 0 answers at once with what we already have.","type":"integer","minimum":0,"maximum":60}},"required":["keywords","geo"]}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Search for places","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"places":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the place. It never changes, and get_place takes it. Google's own id is `identity.cid`."},"identity":{"type":"object","properties":{"cid":{"anyOf":[{"type":"string","pattern":"^\\d{1,25}$"},{"type":"null"}],"description":"Google's id for the place: up to 25 digits, always as a string. It does not fit in a JavaScript number, so reading it as one loses the last digits. Null when Maps didn't give one."},"placeId":{"description":"Google's place ID. Null when Maps didn't give one.","type":["string","null"]},"dataId":{"description":"Google Maps' own id for the listing: two hexadecimal numbers joined by a colon. Null when Maps didn't give one.","type":["string","null"]},"name":{"type":"string","minLength":1,"description":"The business's name, as Maps shows it."},"category":{"description":"The kind of business, in the language of the last search that collected it: \"Bakery\", \"Padaria\".","type":["string","null"]},"mapsUrl":{"type":"string","format":"uri","description":"The place's page on Google Maps."},"description":{"description":"What the business wrote about itself on Maps. Null when it wrote nothing.","type":["string","null"]},"status":{"description":"What its Maps listing said when we collected it (`meta.scrapedAt`), such as \"Permanently closed\".","type":["string","null"]}},"required":["cid","placeId","dataId","name","category","mapsUrl","description","status"],"additionalProperties":false,"description":"Who the place is: its name, category and ids."},"contact":{"type":"object","properties":{"phones":{"type":"array","items":{"type":"string"},"description":"Phone numbers, as Maps shows them. Empty when it lists none."},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"The business's own website. Null when Maps lists none."},"emails":{"description":"Email addresses we found for the place. Sent only on a plan with emails, after you accept the acceptable use policy, and only when we have at least one. So if you have access and `emails` is missing, we have none.","type":"array","items":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"required":["phones","website"],"additionalProperties":false,"description":"How to reach the business."},"location":{"type":"object","properties":{"address":{"description":"The whole address on one line, as Maps writes it.","type":["string","null"]},"completeAddress":{"anyOf":[{"type":"object","properties":{"borough":{"description":"The neighborhood: the bairro, in Brazil.","type":["string","null"]},"street":{"type":["string","null"]},"city":{"type":["string","null"]},"postalCode":{"description":"The postal code: the CEP, in Brazil.","type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["borough","street","city","postalCode","state","country"],"additionalProperties":false},{"type":"null"}],"description":"The same address in parts. Null when Maps didn't split it."},"city":{"description":"The city, taken from `completeAddress`.","type":["string","null"]},"state":{"description":"The state, taken from `completeAddress`.","type":["string","null"]},"country":{"description":"The country, taken from `completeAddress`.","type":["string","null"]},"lat":{"anyOf":[{"type":"number","minimum":-90,"maximum":90},{"type":"null"}],"description":"Latitude in degrees. Null when we have no coordinates, and then `lng` is null too."},"lng":{"anyOf":[{"type":"number","minimum":-180,"maximum":180},{"type":"null"}],"description":"Longitude in degrees. Null exactly when `lat` is."},"plusCode":{"description":"Google's Plus Code for the spot, a short code that works like an address.","type":["string","null"]}},"required":["address","completeAddress","city","state","country","lat","lng","plusCode"],"additionalProperties":false,"description":"Where the place is."},"ratings":{"type":"object","properties":{"rating":{"anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}],"description":"The average star rating, 0 to 5. Null when nobody has rated it."},"reviewCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"How many reviews it has. Null when Maps didn't say."},"reviewsPerRating":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["1","2","3","4","5"]},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"type":"null"}],"description":"How many reviews gave each star count. Stars Google left out are missing here too."}},"required":["rating","reviewCount","reviewsPerRating"],"additionalProperties":false,"description":"The star rating and its reviews."},"hours":{"type":"object","properties":{"timezone":{"description":"The place's time zone, such as America/Sao_Paulo.","type":["string","null"]},"openHours":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"null"}],"description":"Day name to the hours it is open, both in the language of the last search that collected the place. Null when Maps shows no hours."},"popularTimes":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string","pattern":"^(?:[0-9]|1[0-9]|2[0-3])$"},"additionalProperties":{"type":"integer","minimum":0,"maximum":100}}},{"type":"null"}],"description":"Day name to hour (\"0\" to \"23\") to how busy it usually is, from 0 to 100. Null when Maps shows none."}},"required":["timezone","openHours","popularTimes"],"additionalProperties":false,"description":"When it opens and how busy it gets."},"commerce":{"type":"object","properties":{"priceRange":{"description":"The price band Maps shows, such as \"$$\". Null when it shows none.","type":["string","null"]},"about":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean","description":"True when the place has it, false when Maps says it doesn't."},"values":{"type":"array","items":{"type":"string"}}},"required":["name","enabled"],"additionalProperties":false},"description":"What Maps lists in this group, such as a wheelchair-accessible entrance."}},"required":["id","name","options"],"additionalProperties":false},"description":"What the place says about itself on Maps, in groups such as accessibility or payments."},"creditCardsAccepted":{"type":"array","items":{"type":"string"},"description":"The cards it takes, as Maps lists them. Empty when Maps doesn't say."},"menu":{"anyOf":[{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},{"type":"null"}],"description":"A link to its menu. Null when it has none."},"orderOnline":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to order from it online. Empty when Maps lists none."},"reservations":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to book with it. Empty when Maps lists none."}},"required":["priceRange","about","creditCardsAccepted","menu","orderOnline","reservations"],"additionalProperties":false,"description":"Prices, amenities, payments, and links to order or book."},"meta":{"type":"object","properties":{"scrapedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we last collected this place."},"firstSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we first collected this place."},"cached":{"type":"boolean","description":"True when this came from what we already had, which costs nothing."}},"required":["scrapedAt","firstSeenAt","cached"],"additionalProperties":false,"description":"When we collected the place, and whether it cost you a credit."}},"required":["id","identity","contact","location","ratings","hours","commerce","meta"],"additionalProperties":false},"description":"Up to `limit` places. When a collection is running, these are its places so far, each saying whether we already had it. That is how you check what it cost."},"coverage":{"type":"string","enum":["fresh","partial","new"],"description":"How much of the area we had searched when you asked. `fresh`: all of it recently. `new`: none of it. `partial`: some."},"placesKnown":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we already had saved here when you asked. They cost nothing."},"collection":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the collection. get_collection, list_collection_places, cancel_collection and create_export take it."},"kind":{"type":"string","enum":["search","collection"],"description":"`collection` when you asked for it, `search` when a search started it to fill its `limit`."},"status":{"type":"string","enum":["queued","running","succeeded","partial","failed","cancelled"],"description":"`queued` while it waits its turn, `running` while it searches, then `succeeded`, `partial`, `failed` or `cancelled`."},"stopReason":{"anyOf":[{"type":"string","enum":["quota","daily_cap","cancelled","engine","empty"]},{"type":"null"}],"description":"Why it stopped short, or found nothing. A credit limit shows here as soon as it is hit, while the search already in flight finishes. Null when it searched the whole area or reached `maxPlaces`."},"query":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"description":"What it searched for. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"The area, as you gave it: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"type":"string","pattern":"^[a-z]{2}$","description":"The language it searched in. Two letters, such as pt or en."},"minRating":{"description":"Only places rated at least this were kept, from 1 to 5. Null when every place was.","type":["number","null"]},"maxPlaces":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"It stops after this many places: what you asked for, or the most your plan collects at once."},"enrich":{"type":"array","items":{"type":"string","enum":["emails"]},"description":"[\"emails\"] when it also looks for email addresses, which costs one more credit for each place that has one. Empty when it doesn't."}},"required":["keywords","geo","lang","minRating","maxPlaces","enrich"],"additionalProperties":false,"description":"What you asked for, exactly as it ran, with `maxPlaces` filled in from your plan when you left it out."},"area":{"anyOf":[{"anyOf":[{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false}]},{"type":"null"}],"description":"Where it searched, ready to draw: a lat/lng centre with radiusM in metres, or a bbox as [west, south, east, north]. A city is the circle we searched around its centre. Null for an old collection whose city we can no longer place."},"squaresTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches the area takes: one per square of the area, for each term."},"squaresCovered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those we searched recently enough to reuse. Their places cost nothing."},"jobsTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Batches of searching. Each one covers several squares around one point."},"jobsDone":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those batches have finished."},"counts":{"type":"object","properties":{"placesDelivered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places handed over so far: always `placesFresh` plus `placesCached`."},"placesFresh":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we collected for you just now, either new to us or too old to reuse. Each costs one credit."},"placesCached":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we already had saved. They cost nothing."},"creditsCharged":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits taken: one per fresh place, plus one per place we found an email for."},"creditsRefunded":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits given back. A collection that delivers nothing refunds all of them."}},"required":["placesDelivered","placesFresh","placesCached","creditsCharged","creditsRefunded"],"additionalProperties":false,"description":"What it has delivered so far, and what that cost."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","INVALID_TOKEN","PLAN_GATE","AUP_REQUIRED","FORBIDDEN","NOT_FOUND","PLACE_NOT_FOUND","COLLECTION_NOT_FOUND","EXPORT_NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","GEO_UNRESOLVED","UPSTREAM_BLOCKED","RATE_LIMIT_EXCEEDED","QUOTA_EXCEEDED","INTERNAL_ERROR","ENGINE_UNAVAILABLE","SERVICE_UNAVAILABLE","BILLING_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks.","type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},"params":{"description":"The values that fill `messageKey`'s blanks, such as a limit.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},"details":{"description":"More about the error. A quota error names its `scope` here: month, day or concurrency."}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why it failed, shaped like any other error. Null unless `status` is `failed`."},"queuedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we accepted it. ISO 8601 with an offset, as every date here is."},"startedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the first search started. Null while it waits its turn."},"finishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When it ended. Null while it runs."},"cancelRequestedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"Set the moment you cancel. The search already in flight still finishes."},"resultsExpireAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"After this, the counts stay but its places can no longer be listed. Export them first."}},"required":["id","kind","status","stopReason","query","area","squaresTotal","squaresCovered","jobsTotal","jobsDone","counts","error","queuedAt","startedAt","finishedAt","cancelRequestedAt","resultsExpireAt"],"additionalProperties":false},{"type":"null"}],"description":"Collecting the rest, when what we held could not fill `limit`. It stops at `limit` places. Read it again, or follow its stream, to see the new ones arrive. Null when nothing needed collecting, or when `collectionError` says why we could not start."},"collectionError":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","INVALID_TOKEN","PLAN_GATE","AUP_REQUIRED","FORBIDDEN","NOT_FOUND","PLACE_NOT_FOUND","COLLECTION_NOT_FOUND","EXPORT_NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","GEO_UNRESOLVED","UPSTREAM_BLOCKED","RATE_LIMIT_EXCEEDED","QUOTA_EXCEEDED","INTERNAL_ERROR","ENGINE_UNAVAILABLE","SERVICE_UNAVAILABLE","BILLING_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks.","type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},"params":{"description":"The values that fill `messageKey`'s blanks, such as a limit.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},"details":{"description":"More about the error. A quota error names its `scope` here: month, day or concurrency."}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why we could not start collecting the rest: out of credits for today or this month, or already running as many collections as your plan allows. The places we already held still come back."}},"required":["places","coverage","placesKnown","collection","collectionError"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"places.search","returns":"SearchResultDto"},"x-mcp-tool":"search_places"}},"/places/{place}":{"get":{"operationId":"get_place","tags":["Places"],"summary":"Look up a place","description":"Read one saved place, by our id, Google's cid, Google's place ID, or a Google Maps link to it. It never searches: a place we have not saved answers 404, and searching its area with search_places brings it in. Needs an API key. Costs no credits.","parameters":[{"name":"place","in":"path","required":true,"description":"Our id for the place, Google's cid, Google's place ID, or a Google Maps link to it.","schema":{"type":"string","minLength":1,"maxLength":2048,"description":"Our id for the place, Google's cid, Google's place ID, or a Google Maps link to it."}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Look up a place","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the place. It never changes, and get_place takes it. Google's own id is `identity.cid`."},"identity":{"type":"object","properties":{"cid":{"anyOf":[{"type":"string","pattern":"^\\d{1,25}$"},{"type":"null"}],"description":"Google's id for the place: up to 25 digits, always as a string. It does not fit in a JavaScript number, so reading it as one loses the last digits. Null when Maps didn't give one."},"placeId":{"description":"Google's place ID. Null when Maps didn't give one.","type":["string","null"]},"dataId":{"description":"Google Maps' own id for the listing: two hexadecimal numbers joined by a colon. Null when Maps didn't give one.","type":["string","null"]},"name":{"type":"string","minLength":1,"description":"The business's name, as Maps shows it."},"category":{"description":"The kind of business, in the language of the last search that collected it: \"Bakery\", \"Padaria\".","type":["string","null"]},"mapsUrl":{"type":"string","format":"uri","description":"The place's page on Google Maps."},"description":{"description":"What the business wrote about itself on Maps. Null when it wrote nothing.","type":["string","null"]},"status":{"description":"What its Maps listing said when we collected it (`meta.scrapedAt`), such as \"Permanently closed\".","type":["string","null"]}},"required":["cid","placeId","dataId","name","category","mapsUrl","description","status"],"additionalProperties":false,"description":"Who the place is: its name, category and ids."},"contact":{"type":"object","properties":{"phones":{"type":"array","items":{"type":"string"},"description":"Phone numbers, as Maps shows them. Empty when it lists none."},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"The business's own website. Null when Maps lists none."},"emails":{"description":"Email addresses we found for the place. Sent only on a plan with emails, after you accept the acceptable use policy, and only when we have at least one. So if you have access and `emails` is missing, we have none.","type":"array","items":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"required":["phones","website"],"additionalProperties":false,"description":"How to reach the business."},"location":{"type":"object","properties":{"address":{"description":"The whole address on one line, as Maps writes it.","type":["string","null"]},"completeAddress":{"anyOf":[{"type":"object","properties":{"borough":{"description":"The neighborhood: the bairro, in Brazil.","type":["string","null"]},"street":{"type":["string","null"]},"city":{"type":["string","null"]},"postalCode":{"description":"The postal code: the CEP, in Brazil.","type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["borough","street","city","postalCode","state","country"],"additionalProperties":false},{"type":"null"}],"description":"The same address in parts. Null when Maps didn't split it."},"city":{"description":"The city, taken from `completeAddress`.","type":["string","null"]},"state":{"description":"The state, taken from `completeAddress`.","type":["string","null"]},"country":{"description":"The country, taken from `completeAddress`.","type":["string","null"]},"lat":{"anyOf":[{"type":"number","minimum":-90,"maximum":90},{"type":"null"}],"description":"Latitude in degrees. Null when we have no coordinates, and then `lng` is null too."},"lng":{"anyOf":[{"type":"number","minimum":-180,"maximum":180},{"type":"null"}],"description":"Longitude in degrees. Null exactly when `lat` is."},"plusCode":{"description":"Google's Plus Code for the spot, a short code that works like an address.","type":["string","null"]}},"required":["address","completeAddress","city","state","country","lat","lng","plusCode"],"additionalProperties":false,"description":"Where the place is."},"ratings":{"type":"object","properties":{"rating":{"anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}],"description":"The average star rating, 0 to 5. Null when nobody has rated it."},"reviewCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"How many reviews it has. Null when Maps didn't say."},"reviewsPerRating":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["1","2","3","4","5"]},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"type":"null"}],"description":"How many reviews gave each star count. Stars Google left out are missing here too."}},"required":["rating","reviewCount","reviewsPerRating"],"additionalProperties":false,"description":"The star rating and its reviews."},"hours":{"type":"object","properties":{"timezone":{"description":"The place's time zone, such as America/Sao_Paulo.","type":["string","null"]},"openHours":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"null"}],"description":"Day name to the hours it is open, both in the language of the last search that collected the place. Null when Maps shows no hours."},"popularTimes":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string","pattern":"^(?:[0-9]|1[0-9]|2[0-3])$"},"additionalProperties":{"type":"integer","minimum":0,"maximum":100}}},{"type":"null"}],"description":"Day name to hour (\"0\" to \"23\") to how busy it usually is, from 0 to 100. Null when Maps shows none."}},"required":["timezone","openHours","popularTimes"],"additionalProperties":false,"description":"When it opens and how busy it gets."},"commerce":{"type":"object","properties":{"priceRange":{"description":"The price band Maps shows, such as \"$$\". Null when it shows none.","type":["string","null"]},"about":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean","description":"True when the place has it, false when Maps says it doesn't."},"values":{"type":"array","items":{"type":"string"}}},"required":["name","enabled"],"additionalProperties":false},"description":"What Maps lists in this group, such as a wheelchair-accessible entrance."}},"required":["id","name","options"],"additionalProperties":false},"description":"What the place says about itself on Maps, in groups such as accessibility or payments."},"creditCardsAccepted":{"type":"array","items":{"type":"string"},"description":"The cards it takes, as Maps lists them. Empty when Maps doesn't say."},"menu":{"anyOf":[{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},{"type":"null"}],"description":"A link to its menu. Null when it has none."},"orderOnline":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to order from it online. Empty when Maps lists none."},"reservations":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to book with it. Empty when Maps lists none."}},"required":["priceRange","about","creditCardsAccepted","menu","orderOnline","reservations"],"additionalProperties":false,"description":"Prices, amenities, payments, and links to order or book."},"meta":{"type":"object","properties":{"scrapedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we last collected this place."},"firstSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we first collected this place."},"cached":{"type":"boolean","description":"True when this came from what we already had, which costs nothing."}},"required":["scrapedAt","firstSeenAt","cached"],"additionalProperties":false,"description":"When we collected the place, and whether it cost you a credit."}},"required":["id","identity","contact","location","ratings","hours","commerce","meta"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"places.get","returns":"PlaceDto"},"x-mcp-tool":"get_place"}},"/collections":{"post":{"operationId":"create_collection","tags":["Collections"],"summary":"Start a collection","description":"Search a whole area, square by square, and collect up to maxPlaces of the places in it. Answers straight away with the collection, then works through the area in the background. Read the collection again to see how far it has got. Starting one costs nothing: each new place costs one credit as it arrives, and saved places cost nothing. Needs an API key.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any text of 1 to 200 characters, such as your own job id. Send it again with the same body, and you get back what the first call started, as it stands now: nothing starts or costs credits twice. The same key with a different body answers 409. Without a key, a call that got no answer cannot be sent again safely.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"keywords":{"minItems":1,"type":"array","items":{"type":"string"},"description":"What to search for, such as [\"bakery\", \"coffee shop\"]. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"Where to search. Give exactly one of: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"default":"pt","description":"The language to search in. New places come back in it. Two letters, such as pt or en.","type":"string","pattern":"^[a-z]{2}$"},"minRating":{"default":null,"description":"Keep only places rated at least this, from 1 to 5. Null keeps every place.","anyOf":[{"type":"number","minimum":1,"maximum":5},{"type":"null"}]},"maxPlaces":{"description":"Stop after this many places. Defaults to the most your plan collects at once.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"enrich":{"default":[],"description":"Add [\"emails\"] to also look for email addresses. Costs one more credit for each place that has one, and needs a paid plan.","type":"array","items":{"type":"string","enum":["emails"]}}},"required":["keywords","geo"]}}}},"security":[{"apiKey":[]}],"responses":{"202":{"description":"Start a collection","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the collection. get_collection, list_collection_places, cancel_collection and create_export take it."},"kind":{"type":"string","enum":["search","collection"],"description":"`collection` when you asked for it, `search` when a search started it to fill its `limit`."},"status":{"type":"string","enum":["queued","running","succeeded","partial","failed","cancelled"],"description":"`queued` while it waits its turn, `running` while it searches, then `succeeded`, `partial`, `failed` or `cancelled`."},"stopReason":{"anyOf":[{"type":"string","enum":["quota","daily_cap","cancelled","engine","empty"]},{"type":"null"}],"description":"Why it stopped short, or found nothing. A credit limit shows here as soon as it is hit, while the search already in flight finishes. Null when it searched the whole area or reached `maxPlaces`."},"query":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"description":"What it searched for. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"The area, as you gave it: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"type":"string","pattern":"^[a-z]{2}$","description":"The language it searched in. Two letters, such as pt or en."},"minRating":{"description":"Only places rated at least this were kept, from 1 to 5. Null when every place was.","type":["number","null"]},"maxPlaces":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"It stops after this many places: what you asked for, or the most your plan collects at once."},"enrich":{"type":"array","items":{"type":"string","enum":["emails"]},"description":"[\"emails\"] when it also looks for email addresses, which costs one more credit for each place that has one. Empty when it doesn't."}},"required":["keywords","geo","lang","minRating","maxPlaces","enrich"],"additionalProperties":false,"description":"What you asked for, exactly as it ran, with `maxPlaces` filled in from your plan when you left it out."},"area":{"anyOf":[{"anyOf":[{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false}]},{"type":"null"}],"description":"Where it searched, ready to draw: a lat/lng centre with radiusM in metres, or a bbox as [west, south, east, north]. A city is the circle we searched around its centre. Null for an old collection whose city we can no longer place."},"squaresTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches the area takes: one per square of the area, for each term."},"squaresCovered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those we searched recently enough to reuse. Their places cost nothing."},"jobsTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Batches of searching. Each one covers several squares around one point."},"jobsDone":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those batches have finished."},"counts":{"type":"object","properties":{"placesDelivered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places handed over so far: always `placesFresh` plus `placesCached`."},"placesFresh":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we collected for you just now, either new to us or too old to reuse. Each costs one credit."},"placesCached":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we already had saved. They cost nothing."},"creditsCharged":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits taken: one per fresh place, plus one per place we found an email for."},"creditsRefunded":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits given back. A collection that delivers nothing refunds all of them."}},"required":["placesDelivered","placesFresh","placesCached","creditsCharged","creditsRefunded"],"additionalProperties":false,"description":"What it has delivered so far, and what that cost."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","INVALID_TOKEN","PLAN_GATE","AUP_REQUIRED","FORBIDDEN","NOT_FOUND","PLACE_NOT_FOUND","COLLECTION_NOT_FOUND","EXPORT_NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","GEO_UNRESOLVED","UPSTREAM_BLOCKED","RATE_LIMIT_EXCEEDED","QUOTA_EXCEEDED","INTERNAL_ERROR","ENGINE_UNAVAILABLE","SERVICE_UNAVAILABLE","BILLING_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks.","type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},"params":{"description":"The values that fill `messageKey`'s blanks, such as a limit.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},"details":{"description":"More about the error. A quota error names its `scope` here: month, day or concurrency."}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why it failed, shaped like any other error. Null unless `status` is `failed`."},"queuedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we accepted it. ISO 8601 with an offset, as every date here is."},"startedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the first search started. Null while it waits its turn."},"finishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When it ended. Null while it runs."},"cancelRequestedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"Set the moment you cancel. The search already in flight still finishes."},"resultsExpireAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"After this, the counts stay but its places can no longer be listed. Export them first."}},"required":["id","kind","status","stopReason","query","area","squaresTotal","squaresCovered","jobsTotal","jobsDone","counts","error","queuedAt","startedAt","finishedAt","cancelRequestedAt","resultsExpireAt"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"collections.create","returns":"CollectionDto"},"x-mcp-tool":"create_collection"},"get":{"operationId":"list_collections","tags":["Collections"],"summary":"List your collections","description":"Your collections, newest first, with the total so you know how many more there are. Filter by status to find the ones still running. Needs an API key. Costs no credits.","parameters":[{"name":"status","in":"query","required":false,"description":"Show only collections with this status, such as running.","schema":{"description":"Show only collections with this status, such as running.","type":"string","enum":["queued","running","succeeded","partial","failed","cancelled"]}},{"name":"limit","in":"query","required":false,"description":"How many collections to return, from 1 to 100.","schema":{"default":20,"description":"How many collections to return, from 1 to 100.","type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"How many collections to skip, for reading the next page.","schema":{"default":0,"description":"How many collections to skip, for reading the next page.","type":"integer","minimum":0,"maximum":9007199254740991}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"List your collections","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the collection. get_collection, list_collection_places, cancel_collection and create_export take it."},"kind":{"type":"string","enum":["search","collection"],"description":"`collection` when you asked for it, `search` when a search started it to fill its `limit`."},"status":{"type":"string","enum":["queued","running","succeeded","partial","failed","cancelled"],"description":"`queued` while it waits its turn, `running` while it searches, then `succeeded`, `partial`, `failed` or `cancelled`."},"stopReason":{"anyOf":[{"type":"string","enum":["quota","daily_cap","cancelled","engine","empty"]},{"type":"null"}],"description":"Why it stopped short, or found nothing. A credit limit shows here as soon as it is hit, while the search already in flight finishes. Null when it searched the whole area or reached `maxPlaces`."},"query":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"description":"What it searched for. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"The area, as you gave it: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"type":"string","pattern":"^[a-z]{2}$","description":"The language it searched in. Two letters, such as pt or en."},"minRating":{"description":"Only places rated at least this were kept, from 1 to 5. Null when every place was.","type":["number","null"]},"maxPlaces":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"It stops after this many places: what you asked for, or the most your plan collects at once."},"enrich":{"type":"array","items":{"type":"string","enum":["emails"]},"description":"[\"emails\"] when it also looks for email addresses, which costs one more credit for each place that has one. Empty when it doesn't."}},"required":["keywords","geo","lang","minRating","maxPlaces","enrich"],"additionalProperties":false,"description":"What you asked for, exactly as it ran, with `maxPlaces` filled in from your plan when you left it out."},"area":{"anyOf":[{"anyOf":[{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false}]},{"type":"null"}],"description":"Where it searched, ready to draw: a lat/lng centre with radiusM in metres, or a bbox as [west, south, east, north]. A city is the circle we searched around its centre. Null for an old collection whose city we can no longer place."},"squaresTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches the area takes: one per square of the area, for each term."},"squaresCovered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those we searched recently enough to reuse. Their places cost nothing."},"jobsTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Batches of searching. Each one covers several squares around one point."},"jobsDone":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those batches have finished."},"counts":{"type":"object","properties":{"placesDelivered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places handed over so far: always `placesFresh` plus `placesCached`."},"placesFresh":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we collected for you just now, either new to us or too old to reuse. Each costs one credit."},"placesCached":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we already had saved. They cost nothing."},"creditsCharged":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits taken: one per fresh place, plus one per place we found an email for."},"creditsRefunded":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits given back. A collection that delivers nothing refunds all of them."}},"required":["placesDelivered","placesFresh","placesCached","creditsCharged","creditsRefunded"],"additionalProperties":false,"description":"What it has delivered so far, and what that cost."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","INVALID_TOKEN","PLAN_GATE","AUP_REQUIRED","FORBIDDEN","NOT_FOUND","PLACE_NOT_FOUND","COLLECTION_NOT_FOUND","EXPORT_NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","GEO_UNRESOLVED","UPSTREAM_BLOCKED","RATE_LIMIT_EXCEEDED","QUOTA_EXCEEDED","INTERNAL_ERROR","ENGINE_UNAVAILABLE","SERVICE_UNAVAILABLE","BILLING_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks.","type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},"params":{"description":"The values that fill `messageKey`'s blanks, such as a limit.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},"details":{"description":"More about the error. A quota error names its `scope` here: month, day or concurrency."}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why it failed, shaped like any other error. Null unless `status` is `failed`."},"queuedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we accepted it. ISO 8601 with an offset, as every date here is."},"startedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the first search started. Null while it waits its turn."},"finishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When it ended. Null while it runs."},"cancelRequestedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"Set the moment you cancel. The search already in flight still finishes."},"resultsExpireAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"After this, the counts stay but its places can no longer be listed. Export them first."}},"required":["id","kind","status","stopReason","query","area","squaresTotal","squaresCovered","jobsTotal","jobsDone","counts","error","queuedAt","startedAt","finishedAt","cancelRequestedAt","resultsExpireAt"],"additionalProperties":false},"description":"Your collections on this page, newest first."},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every collection matching the filter, not just this page."},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The most collections this page could hold, as you asked."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many collections came before this page."}},"required":["items","total","limit","offset"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"collections.list","returns":"CollectionPageDto"},"x-mcp-tool":"list_collections"}},"/collections/{id}":{"get":{"operationId":"get_collection","tags":["Collections"],"summary":"Read a collection","description":"See where a collection has got to: how much of the area is searched, how many places have arrived, and what it has cost so far. Read it again whenever you want an update. Needs an API key. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The collection's id, as create_collection returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The collection's id, as create_collection returned it."}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Read a collection","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the collection. get_collection, list_collection_places, cancel_collection and create_export take it."},"kind":{"type":"string","enum":["search","collection"],"description":"`collection` when you asked for it, `search` when a search started it to fill its `limit`."},"status":{"type":"string","enum":["queued","running","succeeded","partial","failed","cancelled"],"description":"`queued` while it waits its turn, `running` while it searches, then `succeeded`, `partial`, `failed` or `cancelled`."},"stopReason":{"anyOf":[{"type":"string","enum":["quota","daily_cap","cancelled","engine","empty"]},{"type":"null"}],"description":"Why it stopped short, or found nothing. A credit limit shows here as soon as it is hit, while the search already in flight finishes. Null when it searched the whole area or reached `maxPlaces`."},"query":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"description":"What it searched for. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"The area, as you gave it: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"type":"string","pattern":"^[a-z]{2}$","description":"The language it searched in. Two letters, such as pt or en."},"minRating":{"description":"Only places rated at least this were kept, from 1 to 5. Null when every place was.","type":["number","null"]},"maxPlaces":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"It stops after this many places: what you asked for, or the most your plan collects at once."},"enrich":{"type":"array","items":{"type":"string","enum":["emails"]},"description":"[\"emails\"] when it also looks for email addresses, which costs one more credit for each place that has one. Empty when it doesn't."}},"required":["keywords","geo","lang","minRating","maxPlaces","enrich"],"additionalProperties":false,"description":"What you asked for, exactly as it ran, with `maxPlaces` filled in from your plan when you left it out."},"area":{"anyOf":[{"anyOf":[{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false}]},{"type":"null"}],"description":"Where it searched, ready to draw: a lat/lng centre with radiusM in metres, or a bbox as [west, south, east, north]. A city is the circle we searched around its centre. Null for an old collection whose city we can no longer place."},"squaresTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches the area takes: one per square of the area, for each term."},"squaresCovered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those we searched recently enough to reuse. Their places cost nothing."},"jobsTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Batches of searching. Each one covers several squares around one point."},"jobsDone":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those batches have finished."},"counts":{"type":"object","properties":{"placesDelivered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places handed over so far: always `placesFresh` plus `placesCached`."},"placesFresh":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we collected for you just now, either new to us or too old to reuse. Each costs one credit."},"placesCached":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we already had saved. They cost nothing."},"creditsCharged":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits taken: one per fresh place, plus one per place we found an email for."},"creditsRefunded":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits given back. A collection that delivers nothing refunds all of them."}},"required":["placesDelivered","placesFresh","placesCached","creditsCharged","creditsRefunded"],"additionalProperties":false,"description":"What it has delivered so far, and what that cost."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","INVALID_TOKEN","PLAN_GATE","AUP_REQUIRED","FORBIDDEN","NOT_FOUND","PLACE_NOT_FOUND","COLLECTION_NOT_FOUND","EXPORT_NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","GEO_UNRESOLVED","UPSTREAM_BLOCKED","RATE_LIMIT_EXCEEDED","QUOTA_EXCEEDED","INTERNAL_ERROR","ENGINE_UNAVAILABLE","SERVICE_UNAVAILABLE","BILLING_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks.","type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},"params":{"description":"The values that fill `messageKey`'s blanks, such as a limit.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},"details":{"description":"More about the error. A quota error names its `scope` here: month, day or concurrency."}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why it failed, shaped like any other error. Null unless `status` is `failed`."},"queuedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we accepted it. ISO 8601 with an offset, as every date here is."},"startedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the first search started. Null while it waits its turn."},"finishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When it ended. Null while it runs."},"cancelRequestedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"Set the moment you cancel. The search already in flight still finishes."},"resultsExpireAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"After this, the counts stay but its places can no longer be listed. Export them first."}},"required":["id","kind","status","stopReason","query","area","squaresTotal","squaresCovered","jobsTotal","jobsDone","counts","error","queuedAt","startedAt","finishedAt","cancelRequestedAt","resultsExpireAt"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"collections.get","returns":"CollectionDto"},"x-mcp-tool":"get_collection"},"delete":{"operationId":"cancel_collection","tags":["Collections"],"summary":"Cancel a collection","description":"Stop a collection you no longer want. One that has not started yet stops at once and costs nothing. One already running keeps the places that have arrived and the credits they cost; the search in flight finishes, and nothing new starts. A collection that has already ended cannot be cancelled. Needs an API key. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The collection's id, as create_collection returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The collection's id, as create_collection returned it."}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Cancel a collection","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the collection. get_collection, list_collection_places, cancel_collection and create_export take it."},"kind":{"type":"string","enum":["search","collection"],"description":"`collection` when you asked for it, `search` when a search started it to fill its `limit`."},"status":{"type":"string","enum":["queued","running","succeeded","partial","failed","cancelled"],"description":"`queued` while it waits its turn, `running` while it searches, then `succeeded`, `partial`, `failed` or `cancelled`."},"stopReason":{"anyOf":[{"type":"string","enum":["quota","daily_cap","cancelled","engine","empty"]},{"type":"null"}],"description":"Why it stopped short, or found nothing. A credit limit shows here as soon as it is hit, while the search already in flight finishes. Null when it searched the whole area or reached `maxPlaces`."},"query":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"description":"What it searched for. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"The area, as you gave it: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"type":"string","pattern":"^[a-z]{2}$","description":"The language it searched in. Two letters, such as pt or en."},"minRating":{"description":"Only places rated at least this were kept, from 1 to 5. Null when every place was.","type":["number","null"]},"maxPlaces":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"It stops after this many places: what you asked for, or the most your plan collects at once."},"enrich":{"type":"array","items":{"type":"string","enum":["emails"]},"description":"[\"emails\"] when it also looks for email addresses, which costs one more credit for each place that has one. Empty when it doesn't."}},"required":["keywords","geo","lang","minRating","maxPlaces","enrich"],"additionalProperties":false,"description":"What you asked for, exactly as it ran, with `maxPlaces` filled in from your plan when you left it out."},"area":{"anyOf":[{"anyOf":[{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false}]},{"type":"null"}],"description":"Where it searched, ready to draw: a lat/lng centre with radiusM in metres, or a bbox as [west, south, east, north]. A city is the circle we searched around its centre. Null for an old collection whose city we can no longer place."},"squaresTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches the area takes: one per square of the area, for each term."},"squaresCovered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those we searched recently enough to reuse. Their places cost nothing."},"jobsTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Batches of searching. Each one covers several squares around one point."},"jobsDone":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those batches have finished."},"counts":{"type":"object","properties":{"placesDelivered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places handed over so far: always `placesFresh` plus `placesCached`."},"placesFresh":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we collected for you just now, either new to us or too old to reuse. Each costs one credit."},"placesCached":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we already had saved. They cost nothing."},"creditsCharged":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits taken: one per fresh place, plus one per place we found an email for."},"creditsRefunded":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits given back. A collection that delivers nothing refunds all of them."}},"required":["placesDelivered","placesFresh","placesCached","creditsCharged","creditsRefunded"],"additionalProperties":false,"description":"What it has delivered so far, and what that cost."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","INVALID_TOKEN","PLAN_GATE","AUP_REQUIRED","FORBIDDEN","NOT_FOUND","PLACE_NOT_FOUND","COLLECTION_NOT_FOUND","EXPORT_NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","GEO_UNRESOLVED","UPSTREAM_BLOCKED","RATE_LIMIT_EXCEEDED","QUOTA_EXCEEDED","INTERNAL_ERROR","ENGINE_UNAVAILABLE","SERVICE_UNAVAILABLE","BILLING_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks.","type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},"params":{"description":"The values that fill `messageKey`'s blanks, such as a limit.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},"details":{"description":"More about the error. A quota error names its `scope` here: month, day or concurrency."}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why it failed, shaped like any other error. Null unless `status` is `failed`."},"queuedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we accepted it. ISO 8601 with an offset, as every date here is."},"startedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When the first search started. Null while it waits its turn."},"finishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When it ended. Null while it runs."},"cancelRequestedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"Set the moment you cancel. The search already in flight still finishes."},"resultsExpireAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"After this, the counts stay but its places can no longer be listed. Export them first."}},"required":["id","kind","status","stopReason","query","area","squaresTotal","squaresCovered","jobsTotal","jobsDone","counts","error","queuedAt","startedAt","finishedAt","cancelRequestedAt","resultsExpireAt"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"collections.cancel","returns":"CollectionDto","repeatable":true},"x-mcp-tool":"cancel_collection"}},"/collections/{id}/places":{"get":{"operationId":"list_collection_places","tags":["Collections"],"summary":"List a collection's places","description":"The places a collection has found, oldest first, so a page you have already read stays the same as more arrive. Each place says whether we already had it, which is how you check what you were charged. A page can come back short when a business asked to be left out, so keep reading until you pass the total rather than stopping at a short page. The collection's counts still include those places, which is the record of what you were charged. Needs an API key. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The collection's id, as create_collection returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The collection's id, as create_collection returned it."}},{"name":"limit","in":"query","required":false,"description":"How many places to return, from 1 to 200.","schema":{"default":50,"description":"How many places to return, from 1 to 200.","type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","required":false,"description":"How many places to skip, for reading the next page.","schema":{"default":0,"description":"How many places to skip, for reading the next page.","type":"integer","minimum":0,"maximum":9007199254740991}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"List a collection's places","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the place. It never changes, and get_place takes it. Google's own id is `identity.cid`."},"identity":{"type":"object","properties":{"cid":{"anyOf":[{"type":"string","pattern":"^\\d{1,25}$"},{"type":"null"}],"description":"Google's id for the place: up to 25 digits, always as a string. It does not fit in a JavaScript number, so reading it as one loses the last digits. Null when Maps didn't give one."},"placeId":{"description":"Google's place ID. Null when Maps didn't give one.","type":["string","null"]},"dataId":{"description":"Google Maps' own id for the listing: two hexadecimal numbers joined by a colon. Null when Maps didn't give one.","type":["string","null"]},"name":{"type":"string","minLength":1,"description":"The business's name, as Maps shows it."},"category":{"description":"The kind of business, in the language of the last search that collected it: \"Bakery\", \"Padaria\".","type":["string","null"]},"mapsUrl":{"type":"string","format":"uri","description":"The place's page on Google Maps."},"description":{"description":"What the business wrote about itself on Maps. Null when it wrote nothing.","type":["string","null"]},"status":{"description":"What its Maps listing said when we collected it (`meta.scrapedAt`), such as \"Permanently closed\".","type":["string","null"]}},"required":["cid","placeId","dataId","name","category","mapsUrl","description","status"],"additionalProperties":false,"description":"Who the place is: its name, category and ids."},"contact":{"type":"object","properties":{"phones":{"type":"array","items":{"type":"string"},"description":"Phone numbers, as Maps shows them. Empty when it lists none."},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"The business's own website. Null when Maps lists none."},"emails":{"description":"Email addresses we found for the place. Sent only on a plan with emails, after you accept the acceptable use policy, and only when we have at least one. So if you have access and `emails` is missing, we have none.","type":"array","items":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"required":["phones","website"],"additionalProperties":false,"description":"How to reach the business."},"location":{"type":"object","properties":{"address":{"description":"The whole address on one line, as Maps writes it.","type":["string","null"]},"completeAddress":{"anyOf":[{"type":"object","properties":{"borough":{"description":"The neighborhood: the bairro, in Brazil.","type":["string","null"]},"street":{"type":["string","null"]},"city":{"type":["string","null"]},"postalCode":{"description":"The postal code: the CEP, in Brazil.","type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["borough","street","city","postalCode","state","country"],"additionalProperties":false},{"type":"null"}],"description":"The same address in parts. Null when Maps didn't split it."},"city":{"description":"The city, taken from `completeAddress`.","type":["string","null"]},"state":{"description":"The state, taken from `completeAddress`.","type":["string","null"]},"country":{"description":"The country, taken from `completeAddress`.","type":["string","null"]},"lat":{"anyOf":[{"type":"number","minimum":-90,"maximum":90},{"type":"null"}],"description":"Latitude in degrees. Null when we have no coordinates, and then `lng` is null too."},"lng":{"anyOf":[{"type":"number","minimum":-180,"maximum":180},{"type":"null"}],"description":"Longitude in degrees. Null exactly when `lat` is."},"plusCode":{"description":"Google's Plus Code for the spot, a short code that works like an address.","type":["string","null"]}},"required":["address","completeAddress","city","state","country","lat","lng","plusCode"],"additionalProperties":false,"description":"Where the place is."},"ratings":{"type":"object","properties":{"rating":{"anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}],"description":"The average star rating, 0 to 5. Null when nobody has rated it."},"reviewCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"How many reviews it has. Null when Maps didn't say."},"reviewsPerRating":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["1","2","3","4","5"]},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"type":"null"}],"description":"How many reviews gave each star count. Stars Google left out are missing here too."}},"required":["rating","reviewCount","reviewsPerRating"],"additionalProperties":false,"description":"The star rating and its reviews."},"hours":{"type":"object","properties":{"timezone":{"description":"The place's time zone, such as America/Sao_Paulo.","type":["string","null"]},"openHours":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"null"}],"description":"Day name to the hours it is open, both in the language of the last search that collected the place. Null when Maps shows no hours."},"popularTimes":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string","pattern":"^(?:[0-9]|1[0-9]|2[0-3])$"},"additionalProperties":{"type":"integer","minimum":0,"maximum":100}}},{"type":"null"}],"description":"Day name to hour (\"0\" to \"23\") to how busy it usually is, from 0 to 100. Null when Maps shows none."}},"required":["timezone","openHours","popularTimes"],"additionalProperties":false,"description":"When it opens and how busy it gets."},"commerce":{"type":"object","properties":{"priceRange":{"description":"The price band Maps shows, such as \"$$\". Null when it shows none.","type":["string","null"]},"about":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean","description":"True when the place has it, false when Maps says it doesn't."},"values":{"type":"array","items":{"type":"string"}}},"required":["name","enabled"],"additionalProperties":false},"description":"What Maps lists in this group, such as a wheelchair-accessible entrance."}},"required":["id","name","options"],"additionalProperties":false},"description":"What the place says about itself on Maps, in groups such as accessibility or payments."},"creditCardsAccepted":{"type":"array","items":{"type":"string"},"description":"The cards it takes, as Maps lists them. Empty when Maps doesn't say."},"menu":{"anyOf":[{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},{"type":"null"}],"description":"A link to its menu. Null when it has none."},"orderOnline":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to order from it online. Empty when Maps lists none."},"reservations":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to book with it. Empty when Maps lists none."}},"required":["priceRange","about","creditCardsAccepted","menu","orderOnline","reservations"],"additionalProperties":false,"description":"Prices, amenities, payments, and links to order or book."},"meta":{"type":"object","properties":{"scrapedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we last collected this place."},"firstSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we first collected this place."},"cached":{"type":"boolean","description":"True when this came from what we already had, which costs nothing."}},"required":["scrapedAt","firstSeenAt","cached"],"additionalProperties":false,"description":"When we collected the place, and whether it cost you a credit."}},"required":["id","identity","contact","location","ratings","hours","commerce","meta"],"additionalProperties":false},"description":"The places on this page, in the order they arrived."},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every place in the collection, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most places this page could hold, as you asked."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many places came before this page."}},"required":["items","total","limit","offset"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"collections.places","returns":"PlacePageDto"}}},"/collections/quote":{"post":{"operationId":"quote_collection","tags":["Collections"],"summary":"Quote a collection","description":"See what collecting an area would cost before you start it: how much of it we have searched recently, how many places we have saved there (those cost nothing), how many searches are left to run, and the most it can cost in credits. Needs an API key. Costs no credits and starts nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"keywords":{"minItems":1,"type":"array","items":{"type":"string"},"description":"What to search for, such as [\"bakery\", \"coffee shop\"]. One search per term."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"Where to search. Give exactly one of: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"default":"pt","description":"The language to search in. New places come back in it. Two letters, such as pt or en.","type":"string","pattern":"^[a-z]{2}$"},"minRating":{"default":null,"description":"Keep only places rated at least this, from 1 to 5. Null keeps every place.","anyOf":[{"type":"number","minimum":1,"maximum":5},{"type":"null"}]},"maxPlaces":{"description":"Stop after this many places. Defaults to the most your plan collects at once.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"enrich":{"default":[],"description":"Add [\"emails\"] to also look for email addresses. Costs one more credit for each place that has one, and needs a paid plan.","type":"array","items":{"type":"string","enum":["emails"]}}},"required":["keywords","geo"]}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Quote a collection","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"coverage":{"type":"string","enum":["fresh","partial","new"],"description":"`fresh`: we searched all of it recently. `new`: none of it. `partial`: some."},"squaresTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches the area takes: one per square of the area, for each term."},"squaresCovered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those we searched recently enough to reuse. Their places cost nothing."},"squaresToSearch":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches a collection would still have to run. Each takes a few minutes."},"placesKnown":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we have saved in this area. They cost nothing."},"maxCost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The most this can cost, in credits. It costs less when the new squares hold fewer places."},"sample":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the place. It never changes, and get_place takes it. Google's own id is `identity.cid`."},"identity":{"type":"object","properties":{"cid":{"anyOf":[{"type":"string","pattern":"^\\d{1,25}$"},{"type":"null"}],"description":"Google's id for the place: up to 25 digits, always as a string. It does not fit in a JavaScript number, so reading it as one loses the last digits. Null when Maps didn't give one."},"placeId":{"description":"Google's place ID. Null when Maps didn't give one.","type":["string","null"]},"dataId":{"description":"Google Maps' own id for the listing: two hexadecimal numbers joined by a colon. Null when Maps didn't give one.","type":["string","null"]},"name":{"type":"string","minLength":1,"description":"The business's name, as Maps shows it."},"category":{"description":"The kind of business, in the language of the last search that collected it: \"Bakery\", \"Padaria\".","type":["string","null"]},"mapsUrl":{"type":"string","format":"uri","description":"The place's page on Google Maps."},"description":{"description":"What the business wrote about itself on Maps. Null when it wrote nothing.","type":["string","null"]},"status":{"description":"What its Maps listing said when we collected it (`meta.scrapedAt`), such as \"Permanently closed\".","type":["string","null"]}},"required":["cid","placeId","dataId","name","category","mapsUrl","description","status"],"additionalProperties":false,"description":"Who the place is: its name, category and ids."},"contact":{"type":"object","properties":{"phones":{"type":"array","items":{"type":"string"},"description":"Phone numbers, as Maps shows them. Empty when it lists none."},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"The business's own website. Null when Maps lists none."},"emails":{"description":"Email addresses we found for the place. Sent only on a plan with emails, after you accept the acceptable use policy, and only when we have at least one. So if you have access and `emails` is missing, we have none.","type":"array","items":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"required":["phones","website"],"additionalProperties":false,"description":"How to reach the business."},"location":{"type":"object","properties":{"address":{"description":"The whole address on one line, as Maps writes it.","type":["string","null"]},"completeAddress":{"anyOf":[{"type":"object","properties":{"borough":{"description":"The neighborhood: the bairro, in Brazil.","type":["string","null"]},"street":{"type":["string","null"]},"city":{"type":["string","null"]},"postalCode":{"description":"The postal code: the CEP, in Brazil.","type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["borough","street","city","postalCode","state","country"],"additionalProperties":false},{"type":"null"}],"description":"The same address in parts. Null when Maps didn't split it."},"city":{"description":"The city, taken from `completeAddress`.","type":["string","null"]},"state":{"description":"The state, taken from `completeAddress`.","type":["string","null"]},"country":{"description":"The country, taken from `completeAddress`.","type":["string","null"]},"lat":{"anyOf":[{"type":"number","minimum":-90,"maximum":90},{"type":"null"}],"description":"Latitude in degrees. Null when we have no coordinates, and then `lng` is null too."},"lng":{"anyOf":[{"type":"number","minimum":-180,"maximum":180},{"type":"null"}],"description":"Longitude in degrees. Null exactly when `lat` is."},"plusCode":{"description":"Google's Plus Code for the spot, a short code that works like an address.","type":["string","null"]}},"required":["address","completeAddress","city","state","country","lat","lng","plusCode"],"additionalProperties":false,"description":"Where the place is."},"ratings":{"type":"object","properties":{"rating":{"anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}],"description":"The average star rating, 0 to 5. Null when nobody has rated it."},"reviewCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"How many reviews it has. Null when Maps didn't say."},"reviewsPerRating":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["1","2","3","4","5"]},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"type":"null"}],"description":"How many reviews gave each star count. Stars Google left out are missing here too."}},"required":["rating","reviewCount","reviewsPerRating"],"additionalProperties":false,"description":"The star rating and its reviews."},"hours":{"type":"object","properties":{"timezone":{"description":"The place's time zone, such as America/Sao_Paulo.","type":["string","null"]},"openHours":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"null"}],"description":"Day name to the hours it is open, both in the language of the last search that collected the place. Null when Maps shows no hours."},"popularTimes":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string","pattern":"^(?:[0-9]|1[0-9]|2[0-3])$"},"additionalProperties":{"type":"integer","minimum":0,"maximum":100}}},{"type":"null"}],"description":"Day name to hour (\"0\" to \"23\") to how busy it usually is, from 0 to 100. Null when Maps shows none."}},"required":["timezone","openHours","popularTimes"],"additionalProperties":false,"description":"When it opens and how busy it gets."},"commerce":{"type":"object","properties":{"priceRange":{"description":"The price band Maps shows, such as \"$$\". Null when it shows none.","type":["string","null"]},"about":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean","description":"True when the place has it, false when Maps says it doesn't."},"values":{"type":"array","items":{"type":"string"}}},"required":["name","enabled"],"additionalProperties":false},"description":"What Maps lists in this group, such as a wheelchair-accessible entrance."}},"required":["id","name","options"],"additionalProperties":false},"description":"What the place says about itself on Maps, in groups such as accessibility or payments."},"creditCardsAccepted":{"type":"array","items":{"type":"string"},"description":"The cards it takes, as Maps lists them. Empty when Maps doesn't say."},"menu":{"anyOf":[{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},{"type":"null"}],"description":"A link to its menu. Null when it has none."},"orderOnline":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to order from it online. Empty when Maps lists none."},"reservations":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string","format":"uri","description":"The link to open."},"source":{"type":"string","description":"Who offers it: \"Google\", the business's own site, a delivery app."}},"required":["link","source"],"additionalProperties":false},"description":"Where to book with it. Empty when Maps lists none."}},"required":["priceRange","about","creditCardsAccepted","menu","orderOnline","reservations"],"additionalProperties":false,"description":"Prices, amenities, payments, and links to order or book."},"meta":{"type":"object","properties":{"scrapedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we last collected this place."},"firstSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we first collected this place."},"cached":{"type":"boolean","description":"True when this came from what we already had, which costs nothing."}},"required":["scrapedAt","firstSeenAt","cached"],"additionalProperties":false,"description":"When we collected the place, and whether it cost you a credit."}},"required":["id","identity","contact","location","ratings","hours","commerce","meta"],"additionalProperties":false},"description":"A few of the places we already have, so you can see what is there."}},"required":["coverage","squaresTotal","squaresCovered","squaresToSearch","placesKnown","maxCost","sample"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"collections.quote","returns":"CollectionQuoteDto","repeatable":true},"x-mcp-tool":"quote_collection"}},"/exports":{"post":{"operationId":"create_export","tags":["Exports"],"summary":"Export a collection","description":"Get a link to a collection's places as one file: csv, json or xlsx. The file has the places the collection holds now, even if it is still running. The link opens without an API key for 24 hours, so share it only with people who should see the file. Needs an API key. Costs no credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The collection to export, as create_collection or search_places returned it."},"format":{"default":"csv","description":"The file type: csv, json or xlsx. An xlsx file holds up to 50,000 places.","type":"string","enum":["csv","json","xlsx"]},"locale":{"description":"The language of the column names in csv and xlsx files: en or pt-BR. Defaults to your account's language.","type":"string","enum":["en","pt-BR"]}},"required":["collectionId"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Export a collection","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the export. get_export takes it."},"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The collection the file is built from."},"format":{"type":"string","enum":["csv","json","xlsx"],"description":"The file type: csv, json or xlsx."},"locale":{"type":"string","enum":["en","pt-BR"],"description":"The language of the column names in csv and xlsx files."},"rows":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The places the collection held when the export was made. A place whose business asked to be left out since then is not in the file, so it can hold fewer."},"url":{"type":"string","format":"uri","description":"Opens the file without an API key, until `expiresAt`. Treat it like a password."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When you made the export."},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When `url` stops working, 24 hours after `createdAt`."}},"required":["id","collectionId","format","locale","rows","url","createdAt","expiresAt"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"exports.create","returns":"ExportDto"},"x-mcp-tool":"create_export"}},"/exports/{id}":{"get":{"operationId":"get_export","tags":["Exports"],"summary":"Read an export","description":"Read an export you made, with its download link, while the link still works. After 24 hours, or once the collection's places are deleted, it answers 404: make a new export from the collection. Needs an API key. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The export's id, as create_export returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The export's id, as create_export returned it."}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Read an export","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the export. get_export takes it."},"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The collection the file is built from."},"format":{"type":"string","enum":["csv","json","xlsx"],"description":"The file type: csv, json or xlsx."},"locale":{"type":"string","enum":["en","pt-BR"],"description":"The language of the column names in csv and xlsx files."},"rows":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The places the collection held when the export was made. A place whose business asked to be left out since then is not in the file, so it can hold fewer."},"url":{"type":"string","format":"uri","description":"Opens the file without an API key, until `expiresAt`. Treat it like a password."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When you made the export."},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When `url` stops working, 24 hours after `createdAt`."}},"required":["id","collectionId","format","locale","rows","url","createdAt","expiresAt"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"exports.get","returns":"ExportDto"},"x-mcp-tool":"get_export"}},"/coverage":{"post":{"operationId":"get_coverage","tags":["Coverage"],"summary":"Check an area's coverage","description":"See how much of an area we have already searched for a term, when we last searched it, and how many places we have saved there. Use it to decide whether to collect again or just read the saved places. Needs an API key. Costs no credits and starts nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"keywords":{"minItems":1,"type":"array","items":{"type":"string"},"description":"What you would search for, such as [\"bakery\"]. Coverage is per term: we may have searched an area for one and never for another."},"geo":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","minLength":1}},"required":["location"],"additionalProperties":false},{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusM":{"type":"number","exclusiveMinimum":0}},"required":["lat","lng","radiusM"],"additionalProperties":false},{"type":"object","properties":{"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":4,"maxItems":4}},"required":["bbox"],"additionalProperties":false},{"type":"object","properties":{"cityIbge":{"type":"integer","minimum":1000000,"maximum":9999999},"radiusKm":{"type":"number","exclusiveMinimum":0}},"required":["cityIbge","radiusKm"],"additionalProperties":false}],"description":"The area. Give exactly one of: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm."},"lang":{"default":"pt","description":"The language the search would run in. Two letters, such as pt or en.","type":"string","pattern":"^[a-z]{2}$"}},"required":["keywords","geo"]}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Check an area's coverage","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"coverage":{"type":"string","enum":["fresh","partial","new"],"description":"`fresh`: we searched all of it recently. `new`: none of it. `partial`: some."},"squaresTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches the area takes: one per square of the area, for each term."},"squaresCovered":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of those we searched recently enough to reuse. Their places cost nothing."},"squaresToSearch":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many searches a collection would still have to run. Each takes a few minutes."},"placesKnown":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Places we have saved in this area. They cost nothing."},"searchedAt":{"anyOf":[{"type":"object","properties":{"oldest":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"newest":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["oldest","newest"],"additionalProperties":false},{"type":"null"}],"description":"When we searched the covered squares, oldest and newest. Null when we searched none."},"freshForDays":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How many days a search stays good for. After that, a collection searches the square again."},"emptyFreshForDays":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How many days a search that found no places stays good for. It is far shorter, because finding nothing can also mean the search was blocked."}},"required":["coverage","squaresTotal","squaresCovered","squaresToSearch","placesKnown","searchedAt","freshForDays","emptyFreshForDays"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"coverage.get","returns":"CoverageDto","repeatable":true},"x-mcp-tool":"get_coverage"}},"/usage":{"get":{"operationId":"get_usage","tags":["Usage"],"summary":"Get credit usage","description":"See this month's credits: what your plan includes, what you have used, what is left today and this month, and the same totals for each API key. Needs an API key. Costs no credits.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Get credit usage","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"plan":{"type":"string","enum":["free","starter","pro","scale","internal"],"description":"Your plan's id, such as free or pro."},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$","description":"The month these numbers cover, in UTC, as YYYY-MM."},"creditsIncluded":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits your plan gives you this month."},"creditBalance":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits you bought and haven't used. They never expire."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits you can still spend: what is left of this month's plus the ones you bought."},"dailyCreditCap":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The most credits you can spend in one UTC day. Bought credits don't raise it."},"resetAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When this month's credits start again: midnight UTC on the 1st."},"dailyResetAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When today's limit starts again: the next midnight UTC."},"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the key."},"name":{"type":"string","description":"The name you gave the key."},"prefix":{"type":"string","description":"The first characters of the key, for telling keys apart in a list."},"kind":{"type":"string","enum":["api","dashboard"],"description":"`api` for a key you made, `dashboard` for the console's own."},"revoked":{"type":"boolean","description":"True once the key is revoked. Its usage still counts."},"creditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits spent this month after refunds, bought ones included."},"balanceCreditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The part of `creditsUsed` paid with bought credits, after refunds."},"dailyCreditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits spent today, UTC."},"calls":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many times credits were charged, not how many requests were made. A refund doesn't take one back."}},"required":["id","name","prefix","kind","revoked","creditsUsed","balanceCreditsUsed","dailyCreditsUsed","calls"],"additionalProperties":false},"description":"Usage per API key this month, including revoked keys and the console's own key: their usage is still yours."},"kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["placeFresh","emailFound"],"description":"What the credits paid for: `placeFresh` for new places, `emailFound` for emails."},"creditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits spent this month after refunds, bought ones included."},"balanceCreditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The part of `creditsUsed` paid with bought credits, after refunds."},"dailyCreditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits spent today, UTC."},"calls":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many times credits were charged, not how many requests were made. A refund doesn't take one back."}},"required":["kind","creditsUsed","balanceCreditsUsed","dailyCreditsUsed","calls"],"additionalProperties":false},"description":"This month's usage, split by what the credits paid for."},"creditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits spent this month after refunds, bought ones included."},"balanceCreditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The part of `creditsUsed` paid with bought credits, after refunds."},"dailyCreditsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits spent today, UTC."},"calls":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many times credits were charged, not how many requests were made. A refund doesn't take one back."}},"required":["plan","month","creditsIncluded","creditBalance","creditsRemaining","dailyCreditCap","resetAt","dailyResetAt","keys","kinds","creditsUsed","balanceCreditsUsed","dailyCreditsUsed","calls"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"usage.get","returns":"UsageDto"},"x-mcp-tool":"get_usage"}},"/webhooks":{"post":{"operationId":"create_webhook","tags":["Webhooks"],"summary":"Add a webhook endpoint","description":"Tell us where to POST when a collection ends, instead of asking us every few seconds whether it is done. The answer shows the signing secret once and never again. Store it, then check every request against it. The body carries counts and a link to the places, never the places themselves. Needs an API key and a paid plan. Costs no credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2000,"format":"uri","description":"Where to POST the event. Must start with https:// and resolve to a public address. We will not send your results unencrypted or into a private network."},"events":{"default":["collection.completed","collection.failed"],"minItems":1,"type":"array","items":{"type":"string","enum":["collection.completed","collection.failed"]},"description":"Which events to send here. \"collection.completed\" fires when a collection ends, even one that found no places; \"collection.failed\" fires when an error stops it. A collection you cancel sends neither."},"description":{"type":"string","maxLength":200,"description":"Your own note about this endpoint, such as which of your services it is."}},"required":["url"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Add a webhook endpoint","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the endpoint. update_webhook, delete_webhook, test_webhook and list_webhook_deliveries take it."},"url":{"type":"string","description":"Where we POST events."},"events":{"type":"array","items":{"type":"string"},"description":"The events we send here."},"description":{"description":"Your own note about this endpoint, such as which of your services it is.","type":["string","null"]},"enabled":{"type":"boolean","description":"False when you or we switched it off. We send nothing to it then."},"disabledReason":{"description":"Why we stopped sending here, in English, with the last failure. Null while it works, and when you switched it off yourself.","type":["string","null"]},"disabledReasonKey":{"anyOf":[{"type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},{"type":"null"}],"description":"The same reason as a `messageKey`, to show it in your reader's language, with `disabledReasonParams` filling its blanks. When it is null, show `disabledReason`."},"disabledReasonParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},{"type":"null"}],"description":"The values that fill `disabledReasonKey`'s blanks, such as how many deliveries failed in a row. Null when there are none."},"consecutiveFailures":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Deliveries that failed in a row, after all their tries. Back to zero on the next one that works."},"lastSuccessAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a delivery last arrived. Null until one does."},"lastFailureAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a try last failed. Null if none has."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When you added the endpoint."},"secret":{"anyOf":[{"type":"string","format":"starts_with","pattern":"^whsec_.*"},{"type":"null"}],"description":"The signing secret, shown once, when you add the endpoint, and never again. Store it: it proves a request came from us. Null on every later read."}},"required":["id","url","events","description","enabled","disabledReason","disabledReasonKey","disabledReasonParams","consecutiveFailures","lastSuccessAt","lastFailureAt","createdAt","secret"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"webhooks.create","returns":"WebhookEndpointDto"},"x-mcp-tool":"create_webhook"},"get":{"operationId":"list_webhooks","tags":["Webhooks"],"summary":"List your webhook endpoints","description":"Every endpoint you have added, newest first, with whether it is still receiving events and why we stopped if it is not. Secrets are not shown again after the endpoint is created. Needs an API key and a paid plan. Costs no credits.","security":[{"apiKey":[]}],"responses":{"200":{"description":"List your webhook endpoints","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the endpoint. update_webhook, delete_webhook, test_webhook and list_webhook_deliveries take it."},"url":{"type":"string","description":"Where we POST events."},"events":{"type":"array","items":{"type":"string"},"description":"The events we send here."},"description":{"description":"Your own note about this endpoint, such as which of your services it is.","type":["string","null"]},"enabled":{"type":"boolean","description":"False when you or we switched it off. We send nothing to it then."},"disabledReason":{"description":"Why we stopped sending here, in English, with the last failure. Null while it works, and when you switched it off yourself.","type":["string","null"]},"disabledReasonKey":{"anyOf":[{"type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},{"type":"null"}],"description":"The same reason as a `messageKey`, to show it in your reader's language, with `disabledReasonParams` filling its blanks. When it is null, show `disabledReason`."},"disabledReasonParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},{"type":"null"}],"description":"The values that fill `disabledReasonKey`'s blanks, such as how many deliveries failed in a row. Null when there are none."},"consecutiveFailures":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Deliveries that failed in a row, after all their tries. Back to zero on the next one that works."},"lastSuccessAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a delivery last arrived. Null until one does."},"lastFailureAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a try last failed. Null if none has."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When you added the endpoint."},"secret":{"anyOf":[{"type":"string","format":"starts_with","pattern":"^whsec_.*"},{"type":"null"}],"description":"The signing secret, shown once, when you add the endpoint, and never again. Store it: it proves a request came from us. Null on every later read."}},"required":["id","url","events","description","enabled","disabledReason","disabledReasonKey","disabledReasonParams","consecutiveFailures","lastSuccessAt","lastFailureAt","createdAt","secret"],"additionalProperties":false}},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"webhooks.list","returns":"WebhookEndpointDto[]"},"x-mcp-tool":"list_webhooks"}},"/webhooks/{id}":{"post":{"operationId":"update_webhook","tags":["Webhooks"],"summary":"Change a webhook endpoint","description":"Change which events an endpoint receives, rename it, or switch it off and on. This is how an endpoint comes back after we stopped sending to it: fix your server, then set enabled to true. The failure count starts again from zero. Whatever you leave out stays as it was. Needs an API key and a paid plan. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint's id, as create_webhook returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The endpoint's id, as create_webhook returned it."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"description":"False to stop sending here without deleting it. True to start again after we switched it off.","type":"boolean"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["collection.completed","collection.failed"]},"description":"Which events to send here. \"collection.completed\" fires when a collection ends, even one that found no places; \"collection.failed\" fires when an error stops it. A collection you cancel sends neither."},"description":{"anyOf":[{"type":"string","maxLength":200,"description":"Your own note about this endpoint, such as which of your services it is."},{"type":"null"}]}}}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Change a webhook endpoint","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the endpoint. update_webhook, delete_webhook, test_webhook and list_webhook_deliveries take it."},"url":{"type":"string","description":"Where we POST events."},"events":{"type":"array","items":{"type":"string"},"description":"The events we send here."},"description":{"description":"Your own note about this endpoint, such as which of your services it is.","type":["string","null"]},"enabled":{"type":"boolean","description":"False when you or we switched it off. We send nothing to it then."},"disabledReason":{"description":"Why we stopped sending here, in English, with the last failure. Null while it works, and when you switched it off yourself.","type":["string","null"]},"disabledReasonKey":{"anyOf":[{"type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},{"type":"null"}],"description":"The same reason as a `messageKey`, to show it in your reader's language, with `disabledReasonParams` filling its blanks. When it is null, show `disabledReason`."},"disabledReasonParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},{"type":"null"}],"description":"The values that fill `disabledReasonKey`'s blanks, such as how many deliveries failed in a row. Null when there are none."},"consecutiveFailures":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Deliveries that failed in a row, after all their tries. Back to zero on the next one that works."},"lastSuccessAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a delivery last arrived. Null until one does."},"lastFailureAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a try last failed. Null if none has."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When you added the endpoint."},"secret":{"anyOf":[{"type":"string","format":"starts_with","pattern":"^whsec_.*"},{"type":"null"}],"description":"The signing secret, shown once, when you add the endpoint, and never again. Store it: it proves a request came from us. Null on every later read."}},"required":["id","url","events","description","enabled","disabledReason","disabledReasonKey","disabledReasonParams","consecutiveFailures","lastSuccessAt","lastFailureAt","createdAt","secret"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"webhooks.update","returns":"WebhookEndpointDto","repeatable":true},"x-mcp-tool":"update_webhook"},"delete":{"operationId":"delete_webhook","tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Stop sending to an endpoint and forget it, along with the record of what we sent there. To pause one instead, set enabled to false. That keeps the secret, so you do not have to change your code to turn it back on. Needs an API key and a paid plan. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint's id, as create_webhook returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The endpoint's id, as create_webhook returned it."}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Delete a webhook endpoint","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Our id for the endpoint. update_webhook, delete_webhook, test_webhook and list_webhook_deliveries take it."},"url":{"type":"string","description":"Where we POST events."},"events":{"type":"array","items":{"type":"string"},"description":"The events we send here."},"description":{"description":"Your own note about this endpoint, such as which of your services it is.","type":["string","null"]},"enabled":{"type":"boolean","description":"False when you or we switched it off. We send nothing to it then."},"disabledReason":{"description":"Why we stopped sending here, in English, with the last failure. Null while it works, and when you switched it off yourself.","type":["string","null"]},"disabledReasonKey":{"anyOf":[{"type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},{"type":"null"}],"description":"The same reason as a `messageKey`, to show it in your reader's language, with `disabledReasonParams` filling its blanks. When it is null, show `disabledReason`."},"disabledReasonParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},{"type":"null"}],"description":"The values that fill `disabledReasonKey`'s blanks, such as how many deliveries failed in a row. Null when there are none."},"consecutiveFailures":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Deliveries that failed in a row, after all their tries. Back to zero on the next one that works."},"lastSuccessAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a delivery last arrived. Null until one does."},"lastFailureAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When a try last failed. Null if none has."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When you added the endpoint."},"secret":{"anyOf":[{"type":"string","format":"starts_with","pattern":"^whsec_.*"},{"type":"null"}],"description":"The signing secret, shown once, when you add the endpoint, and never again. Store it: it proves a request came from us. Null on every later read."}},"required":["id","url","events","description","enabled","disabledReason","disabledReasonKey","disabledReasonParams","consecutiveFailures","lastSuccessAt","lastFailureAt","createdAt","secret"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"webhooks.delete","returns":"WebhookEndpointDto","repeatable":true},"x-mcp-tool":"delete_webhook"}},"/webhooks/{id}/test":{"post":{"operationId":"test_webhook","tags":["Webhooks"],"summary":"Send a test event","description":"Send a \"ping\" to one of your endpoints now, so you can check your code reads it and the signature checks out before a real collection depends on it. Answers straight away with the delivery; read the deliveries list a moment later to see what your server said. Needs an API key and a paid plan. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint's id, as create_webhook returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The endpoint's id, as create_webhook returned it."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"message":{"default":"This is a test from your gmaps.dev account.","description":"What the test event should say, so you can spot it in your logs.","type":"string","minLength":1,"maxLength":200}}}}}},"security":[{"apiKey":[]}],"responses":{"202":{"description":"Send a test event","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The event's `id`, which also arrives in the x-gmaps-delivery header. Match it to a request your server logged."},"event":{"type":"string","description":"The event's type, such as collection.completed."},"status":{"type":"string","enum":["pending","delivered","failed"],"description":"`pending` while we're still trying, then `delivered` or `failed`."},"attempts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many tries it has taken."},"responseStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The HTTP status your server answered, or null if it never answered."},"error":{"description":"What went wrong and how to fix it, in English. Null when nothing did.","type":["string","null"]},"errorKey":{"anyOf":[{"type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},{"type":"null"}],"description":"The same failure as a `messageKey`, to show it in your reader's language, with `errorParams` filling its blanks. When it is null, show `error`."},"errorParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},{"type":"null"}],"description":"The values that fill `errorKey`'s blanks, such as the status your server answered. Null when there are none."},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When it arrived. Null until it does."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we queued it: when the event happened, or you sent a test."}},"required":["id","event","status","attempts","responseStatus","error","errorKey","errorParams","deliveredAt","createdAt"],"additionalProperties":false},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"webhooks.test","returns":"WebhookDeliveryDto"},"x-mcp-tool":"test_webhook"}},"/webhooks/{id}/deliveries":{"get":{"operationId":"list_webhook_deliveries","tags":["Webhooks"],"summary":"List an endpoint's deliveries","description":"What we sent to one endpoint, newest first: which event, whether it arrived, how many tries it took, and what your server answered. This is where to look when an event never showed up. Kept for 7 days. Needs an API key and a paid plan. Costs no credits.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint's id, as create_webhook returned it.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The endpoint's id, as create_webhook returned it."}},{"name":"limit","in":"query","required":false,"description":"How many deliveries to return, newest first, from 1 to 100.","schema":{"default":20,"description":"How many deliveries to return, newest first, from 1 to 100.","type":"integer","minimum":1,"maximum":100}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"List an endpoint's deliveries","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The event's `id`, which also arrives in the x-gmaps-delivery header. Match it to a request your server logged."},"event":{"type":"string","description":"The event's type, such as collection.completed."},"status":{"type":"string","enum":["pending","delivered","failed"],"description":"`pending` while we're still trying, then `delivered` or `failed`."},"attempts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many tries it has taken."},"responseStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The HTTP status your server answered, or null if it never answered."},"error":{"description":"What went wrong and how to fix it, in English. Null when nothing did.","type":["string","null"]},"errorKey":{"anyOf":[{"type":"string","enum":["serverErrors.validation","serverErrors.unauthorized","serverErrors.keyInactive","serverErrors.signInRequired","serverErrors.planGateEmails","serverErrors.planGateWebhooks","serverErrors.planGateContact","serverErrors.aupRequired","serverErrors.forbidden","serverErrors.accountSuspended","serverErrors.accountDeletionRequested","serverErrors.accountDeleted","serverErrors.lastStaff","serverErrors.notFound","serverErrors.placeNotFound","serverErrors.placeShortLink","serverErrors.placeLinkNotOne","serverErrors.placeRefUnreadable","serverErrors.collectionNotFound","serverErrors.collectionEnded","serverErrors.collectionPlacesDeleted","serverErrors.exportNotFound","serverErrors.exportNothingYet","serverErrors.exportNothingFound","serverErrors.conflict","serverErrors.payloadTooLarge","serverErrors.geoUnresolved","serverErrors.cityAmbiguous","serverErrors.cityDidYouMean","serverErrors.cityUnknown","serverErrors.cityIbgeUnknown","serverErrors.areaTooLarge","serverErrors.radiusTooLarge","serverErrors.noSearchTerms","serverErrors.tooManyTerms","serverErrors.maxPlacesOverPlan","serverErrors.xlsxTooLarge","serverErrors.keyLimit","serverErrors.subscriptionOpen","serverErrors.checkoutOpen","serverErrors.webhookNotHttps","serverErrors.webhookCredentials","serverErrors.webhookPrivateAddress","serverErrors.webhookNoAddress","serverErrors.webhookDuplicate","serverErrors.webhookUnreachable","serverErrors.webhookTimeout","serverErrors.webhookStatus","serverErrors.webhookRedirect","serverErrors.webhookStopped","serverErrors.webhookOff","serverErrors.upstreamBlocked","serverErrors.rateLimit","serverErrors.quotaMonth","serverErrors.quotaDay","serverErrors.concurrency","serverErrors.internal","serverErrors.engineUnavailable","serverErrors.collectionEngineFailed","serverErrors.serviceUnavailable","serverErrors.billingUnavailable","serverErrors.billingCurrencyUnavailable"]},{"type":"null"}],"description":"The same failure as a `messageKey`, to show it in your reader's language, with `errorParams` filling its blanks. When it is null, show `error`."},"errorParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number"]}},{"type":"null"}],"description":"The values that fill `errorKey`'s blanks, such as the status your server answered. Null when there are none."},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"When it arrived. Null until it does."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When we queued it: when the event happened, or you sent a test."}},"required":["id","event","status","attempts","responseStatus","error","errorKey","errorParams","deliveredAt","createdAt"],"additionalProperties":false}},"meta":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Every item that matches, not just this page."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The most items a page holds."},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many items came before this page."},"hasMore":{"type":"boolean","description":"True when another page follows."}},"required":["total","limit","offset","hasMore"],"additionalProperties":false},{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits this call took."},"creditsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Credits left after this call, this month's and bought ones together."},"requestId":{"type":"string","minLength":1,"description":"This call's id. Send it to support if something went wrong."},"cached":{"description":"True when this response used only saved results.","type":"boolean"}},"required":["cost","creditsRemaining","requestId"],"additionalProperties":false}]}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-sdk":{"method":"webhooks.deliveries","returns":"WebhookDeliveryDto[]"},"x-mcp-tool":"list_webhook_deliveries"}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","INVALID_TOKEN","PLAN_GATE","AUP_REQUIRED","FORBIDDEN","NOT_FOUND","PLACE_NOT_FOUND","COLLECTION_NOT_FOUND","EXPORT_NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","GEO_UNRESOLVED","UPSTREAM_BLOCKED","RATE_LIMIT_EXCEEDED","QUOTA_EXCEEDED","INTERNAL_ERROR","ENGINE_UNAVAILABLE","SERVICE_UNAVAILABLE","BILLING_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"type":"string","description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks."},"params":{"type":"object","additionalProperties":{"type":["string","number"]},"description":"The values that fill `messageKey`'s blanks, such as a limit."},"details":{"description":"More about this error, such as retryAfterSecs."}}}}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Send your API key as \"Authorization: Bearer gm_…\"."}}}}