Skip to content

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 Code setup
claude mcp add --transport http localschema https://local-schema-beacon.lovable.app/mcp \
  --header "Authorization: Bearer ls_your_api_key"
ToolWhat it doesAccess
list_business_typesSupported schema.org LocalBusiness subtypesFree
generate_schemaBusiness details → JSON-LD, script tag and validationFree
validate_schemaValidate JSON-LD, a script tag or a whole HTML pageFree
validate_pageFetch a live page and audit its structured dataFree
get_embed_snippetInstall snippet and status for a hosted embed keyFree
list_clientsClients with client-wide embed and white-label report link Pro key
save_clientCreate or update a client; turn its report link on or off Pro key
list_locationsSaved locations with publish state and latest health score Pro key
get_locationOne location's fields, JSON-LD and validation Pro key
save_locationCreate or update a location and optionally publish it Pro key
run_health_checkValidate, 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.

Agent prompt
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

EndpointWhat it doesLimit
POST /generateBusiness fields → JSON-LD, script tag and validation60 / min
POST /validateCheck existing JSON-LD, a script tag or a whole HTML page60 / min
POST /check-urlFetch a live page and audit its structured data10 / min · 200 / day · 60 / hour per website
GET /embed-snippet?key=…Install snippet + status for a hosted embed120 / min
GET /business-typesSupported 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
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"]
  }'
Response (abridged)
{
  "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", … }
}
JavaScript
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
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
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
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_… or X-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.

EndpointWhat it doesLimit per key
GET /clientsClients with client-wide embed and report link240 / min
POST /clientsCreate or update a client; turn its report on or off60 / min
GET /locations?client_id=…Saved locations with publish state and health score240 / min
POST /locationsCreate or update a location, optionally publish it60 / min
GET /locations/{id}One location's fields, JSON-LD and validation240 / min
POST /locations/{id}/health-checkValidate, scan the website and record a check60 / hour
Create and publish a location
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" }]
    }
  }'
Change only the opening hours
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" }] } }'
Run a health check
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.

Error response
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" }]
  }
}
Missing key
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:

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.