Developers & AI agents
LocalBusiness structured data, one API call away
Website builders and coding agents — Lovable, Cursor, Claude Code and friends — can generate valid schema.org JSON-LD, validate it against Google's rich result rules, audit a live page and install hosted embeds. Use the remote MCP server or plain REST: free and keyless for schema work, with Pro API keys for managing client locations.
- No key for schema work
- Generate, validate and audit from a server, a browser or an agent sandbox. CORS is open.
- Fair-use limits
- Per client IP; every response carries X-RateLimit-* headers.
- Same engine as the app
- Identical output to the LocalSchema builder and hosted embeds.
Connect via MCP
LocalSchema runs a remote MCP server (Streamable HTTP) at https://local-schema-beacon.lovable.app/mcp. Add it to your agent and it can call the tools below directly. Leave the header out to use only the free tools; add a Pro API key (see API keys) for the account tools. The key always travels as a connection header, never as a tool argument.
Add to Terminal
claude mcp add --transport http localschema https://local-schema-beacon.lovable.app/mcp \
--header "Authorization: Bearer ls_your_api_key"| Tool | What it does | Access |
|---|---|---|
| list_business_types | Supported schema.org LocalBusiness subtypes | Free |
| generate_schema | Business details → JSON-LD, script tag and validation | Free |
| validate_schema | Validate JSON-LD, a script tag or a whole HTML page | Free |
| validate_page | Fetch a live page and audit its structured data | Free |
| get_embed_snippet | Install snippet and status for a hosted embed key | Free |
| list_clients | Clients with client-wide embed and white-label report link | Pro key |
| save_client | Create or update a client; turn its report link on or off | Pro key |
| list_locations | Saved locations with publish state and latest health score | Pro key |
| get_location | One location's fields, JSON-LD and validation | Pro key |
| save_location | Create or update a location and optionally publish it | Pro key |
| run_health_check | Validate, scan the website and record a health check | Pro key |
Free tools share the REST limits below per client address. Claude Desktop needs the mcp-remote bridge shown in its tab.
Paste this into your AI builder
Drop the prompt below into Lovable, Cursor, Claude Code or any agent that can make HTTP requests. It points the agent at the OpenAPI spec and tells it how to place and verify the markup.
Add LocalBusiness structured data to this site using the LocalSchema API (free, no key; OpenAPI: https://local-schema-beacon.lovable.app/openapi.json).
1. POST https://local-schema-beacon.lovable.app/api/public/v1/generate with the business details as JSON:
businessType (most specific schema.org type, e.g. "Dentist"; list: GET https://local-schema-beacon.lovable.app/api/public/v1/business-types),
name, url, telephone, address {streetAddress, addressLocality, postalCode, addressCountry},
openingHours [{days: "Mo-Fr", opens: "09:00", closes: "17:00"}], services, sameAs.
2. Insert the returned "script_tag" into the <head> of the homepage (or each location page).
3. Fix anything in "validation.issues" with severity "error", then call /generate again.
4. After deploying, POST https://local-schema-beacon.lovable.app/api/public/v1/check-url with {"url": "<live page>"} and confirm business.validation.valid is true.
If you support MCP, connect to https://local-schema-beacon.lovable.app/mcp instead and use the generate_schema and validate_page tools.Endpoints
Base URL https://local-schema-beacon.lovable.app/api/public/v1
| Endpoint | What it does | Limit |
|---|---|---|
| POST /generate | Business fields → JSON-LD, script tag and validation | 60 / min |
| POST /validate | Check existing JSON-LD, a script tag or a whole HTML page | 60 / min |
| POST /check-url | Fetch a live page and audit its structured data | 10 / min · 200 / day · 60 / hour per website |
| GET /embed-snippet?key=… | Install snippet + status for a hosted embed | 120 / min |
| GET /business-types | Supported schema.org LocalBusiness subtypes | — |
Generate JSON-LD
Send flat business fields; get back the JSON-LD object, a ready-to-paste <script> tag and a validation report. Days not listed in openingHours are closed; add two entries for split hours. Holiday hours, ratings and reviews are Pro features and are left out of free output (the response says so in notes).
curl -X POST https://local-schema-beacon.lovable.app/api/public/v1/generate \
-H "Content-Type: application/json" \
-d '{
"businessType": "Plumber",
"name": "Lone Star Plumbing",
"url": "https://lonestarplumbing.example",
"telephone": "+1 512-555-0100",
"address": {
"streetAddress": "1200 Congress Ave",
"addressLocality": "Austin",
"addressRegion": "TX",
"postalCode": "78701",
"addressCountry": "US"
},
"openingHours": [
{ "days": "Mo-Fr", "opens": "07:00", "closes": "19:00" },
{ "days": "Sa", "opens": "08:00", "closes": "14:00" }
],
"areaServed": ["Austin", "Round Rock"],
"services": [{ "name": "Emergency repair", "price": 129, "priceType": "from" }],
"sameAs": ["https://www.yelp.com/biz/lone-star-plumbing-austin"]
}'{
"business_type": "Plumber",
"jsonld": { "@context": "https://schema.org", "@type": "Plumber", "name": "Lone Star Plumbing", … },
"script_tag": "<script type=\"application/ld+json\">…</script>",
"validation": {
"valid": true,
"rich_result_status": "eligible_with_warnings",
"score": 88,
"errors": 0,
"warnings": 3,
"issues": [{ "severity": "warning", "property": "geo", "title": "Add geo coordinates", "message": "…" }]
},
"notes": [],
"testing": { "rich_results_test": "https://search.google.com/test/rich-results", … }
}const res = await fetch("https://local-schema-beacon.lovable.app/api/public/v1/generate", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ businessType: "Restaurant", name: "Trattoria Fiore", servesCuisine: ["Italian"] }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { script_tag, validation } = await res.json();Validate existing markup
Accepts a JSON-LD object or string, a script tag, or a full HTML page. Finds the LocalBusiness entity (any subtype, inside @graph too) and checks Google's required and recommended properties, opening hours, phone and URL formats.
curl -X POST https://local-schema-beacon.lovable.app/api/public/v1/validate \
-H "Content-Type: application/json" \
-d '{ "jsonld": { "@context": "https://schema.org", "@type": "Dentist", "name": "Bright Smile Dental" } }'
# or send a whole page: { "html": "<!doctype html>…" }Health-check a live page
Fetches the page (public addresses only, 8-second timeout, up to five redirects), lists every JSON-LD block and type, validates the business markup, detects LocalSchema hosted embeds and returns concrete recommendations plus links to Google's Rich Results Test.
curl "https://local-schema-beacon.lovable.app/api/public/v1/check-url?url=https://example.com/contact"Hosted embed snippets
Agencies on LocalSchema Pro publish locations to a hosted script: paste it once and every update reaches the site. Given a key (loc_… for one location, org_… for a client with several), this returns the script tag and whether it's serving.
curl "https://local-schema-beacon.lovable.app/api/public/v1/embed-snippet?key=loc_1a2b3c4d5e"API keys
Account endpoints and MCP tools act on your LocalSchema workspace, so they need a key. Create one in Settings → API keys while you're on Pro or the free trial. Keys look like ls_your_api_key (in reality ls_ plus 48 hex characters), are shown once and stored only as a hash. Up to 10 active keys per account; revoke any of them at any time.
- Send it as
Authorization: Bearer ls_…orX-API-Key: ls_…. - A key reaches every client and location in its account. It stops working when Pro ends and starts again when you resubscribe.
- Keep keys in environment variables or your agent's secret settings — never in chat messages, front-end code or a repository.
Clients & locations
With a key, agents can do what you do in the dashboard: add clients, create and update locations, publish them to the hosted embed and run health checks. Writes follow your plan's location limit and the same validation as the builder. When updating, only the fields you send change; the address merges field by field and lists are replaced.
| Endpoint | What it does | Limit per key |
|---|---|---|
| GET /clients | Clients with client-wide embed and report link | 240 / min |
| POST /clients | Create or update a client; turn its report on or off | 60 / min |
| GET /locations?client_id=… | Saved locations with publish state and health score | 240 / min |
| POST /locations | Create or update a location, optionally publish it | 60 / min |
| GET /locations/{id} | One location's fields, JSON-LD and validation | 240 / min |
| POST /locations/{id}/health-check | Validate, scan the website and record a check | 60 / hour |
curl -X POST https://local-schema-beacon.lovable.app/api/public/v1/locations \
-H "Authorization: Bearer $LOCALSCHEMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"publish": true,
"business": {
"businessType": "Dentist",
"name": "Bright Smile Dental — Haren",
"url": "https://brightsmile.example/haren",
"telephone": "+31 50 211 4481",
"address": { "streetAddress": "Rijksstraatweg 120", "addressLocality": "Haren", "postalCode": "9752 BL", "addressCountry": "NL" },
"openingHours": [{ "days": "Mo-Fr", "opens": "08:30", "closes": "17:00" }]
}
}'curl -X POST https://local-schema-beacon.lovable.app/api/public/v1/locations \
-H "X-API-Key: $LOCALSCHEMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "location_id": "<id from the create response>", "publish": true,
"business": { "openingHours": [{ "days": "Mo-Th", "opens": "08:30", "closes": "17:00" },
{ "days": "Fr", "opens": "08:30", "closes": "13:00" }] } }'curl -X POST https://local-schema-beacon.lovable.app/api/public/v1/locations/<id>/health-check \
-H "Authorization: Bearer $LOCALSCHEMA_API_KEY"Errors & limits
Errors use one envelope with a stable code: invalid_input (422), bad_request (400), not_found (404), payload_too_large (413), rate_limited (429, with Retry-After) and unavailable (502/503). Bodies up to 600 KB.
Key-protected calls add missing_api_key and invalid_api_key (401), pro_required and location_limit (403). MCP tools return the same codes and messages as tool errors.
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "invalid_input",
"message": "Some business fields are invalid.",
"details": [{ "path": "openingHours.0.opens", "message": "Use 24-hour HH:MM, e.g. 09:00" }]
}
}HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="LocalSchema API"
{
"error": {
"code": "missing_api_key",
"message": "This needs a LocalSchema Pro API key. Create one under Settings → API keys …"
}
}Discovery for agents
Agents and registries can find LocalSchema's MCP server and API without reading this page:
- /mcp/server-card— MCP server card, transport, authentication and tools
- /.well-known/mcp/server-card.json— Server card (well-known), same card at the well-known path
- /.well-known/ai-catalog.json— AI catalog, lists the MCP server and REST API
- /.well-known/api-catalog— API catalog, RFC 9727 linkset: OpenAPI, docs, status
- /openapi.json— OpenAPI 3.1, every REST endpoint, including key-protected ones
- /llms.txt— llms.txt, site summary for language models
Managing schema for many clients?
LocalSchema Pro keeps up to 25 locations in one dashboard, serves them through hosted embeds, re-checks every site weekly and includes API keys for your agents.