Places with website contacts

POST https://tools.yukai.uk/api/v1/places/enriched

Find businesses and read their websites for contact details. Same search as /places/search (at most 10 places per call), and each business's own website (home page and a few contact pages, plain HTTP, robots.txt respected) is read for e-mail addresses, phone numbers and social profiles. Source values are never overwritten: what a website adds is returned in enrichedEmails, enrichedPhones, enrichedSocials and an enrichment object per place (status: found, nothing_found, unreachable, robots_disallowed, profile_page, no_website_in_source; pages read; where each e-mail was found). E-mails are role addresses (info@, contact@, sales@) only; personal addresses are withheld. A website shared by several places (a chain) is read once and each place keeps its own id. A place without a website in the source is not "a business without a website": the website is unknown. The page loading does not show that the business is still operating. Typical time 5-15 s.

Cost

Credits: 27 per place ($0.0027 per place). 540 credits are reserved before the call; the call is then settled on the real number of items returned. Failed calls are free. Source price: places-database/place-enriched.

Input

Send a JSON body (POST) or the same fields as a query string (GET).

Required: location.

Field	Type	Default	Description
`location` required	string		A city with its 2-letter country code (`Berlin, DE`, `Austin, US`; country names such as `Lisbon, Portugal` work too), or a bounding box `west,south,east,north` of up to 2 square degrees. Cities are cut out along their real boundary.
`limit`	integer	`5`	Places per call (each website is read, so the limit is lower).
`category`	string		One or more Overture categories, comma-separated (up to 5): `restaurant`, `dental_clinic`, `real_estate_agent`, `hotel`, `attorney_or_law_firm`... Plain words (`dentist`, `lawyers`) and plurals work; a parent category (`food_and_drink`, `health_and_medical`) includes everything under it. Empty = all categories. When nothing matches, `hint` lists the categories that exist there.
`offset`	integer	`0`	Skip this many places (paging, best-scored first).
`minConfidence`	number	`0.85`	Overture's confidence (0.5-1) that the place exists. Closed places are always removed.
`requireWebsite`	boolean	`false`	Only places with a website.
`requirePhone`	boolean	`false`	Only places with a phone number.
`requireEmail`	boolean	`false`	Only places with a role e-mail address (info@, contact@...) in the source data.

Examples

Replace tt_live_XXXX with your key from the pricing page.

curl

curl -i -X POST "https://tools.yukai.uk/api/v1/places/enriched" \
  -H "Authorization: Bearer tt_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"location":"Berlin, DE"}'

JavaScript (fetch)

const res = await fetch("https://tools.yukai.uk/api/v1/places/enriched", {
  method: "POST",
  headers: { "Authorization": "Bearer tt_live_XXXX", "Content-Type": "application/json" },
  body: JSON.stringify({"location":"Berlin, DE"}),
});
console.log(res.status, res.headers.get("x-credits-charged"), res.headers.get("x-credits-balance"));
console.log(await res.json());

Python (requests)

import requests

r = requests.post(
    "https://tools.yukai.uk/api/v1/places/enriched",
    headers={"Authorization": "Bearer tt_live_XXXX"},
    json={"location": "Berlin, DE"},
    timeout=120,
)
print(r.status_code, r.headers.get("x-credits-charged"), r.headers.get("x-credits-balance"))
print(r.json())

Response

JSON with "success": true and the result fields; on failure {"success": false, "error": {"code", "message", "retryable"}} and no credits are used. Every answer carries x-credits-charged (credits used) and x-credits-balance (balance after the call); check the balance any time with GET https://tools.yukai.uk/v1/billing/balance.

Full field list and response schema: OpenAPI spec places (its servers entry is the marketplace gateway; call https://tools.yukai.uk with your key).

← All routes · Pricing