# Woosmap APIs — rules for coding agents
#
# Canonical location: https://developers.woosmap.com/llms-rules.txt
# Reference this URL from your agent's instructions file rather than pasting a
# copy, so the rules stay current when a convention changes.

## Before writing a call

Read the endpoint page under https://developers.woosmap.com/api-reference/ first.
Those pages are generated from the OpenAPI spec and are authoritative for
parameter names, types, required flags, defaults, response schemas and rate
limits.

Product pages and code samples are narrative. They show one working call and
omit most parameters. Do not infer a request shape from them.

Never use a Woosmap parameter that does not appear on the endpoint's reference
page.

## Where to look

- Routing index, maps a question to the page that answers it:
  https://developers.woosmap.com/llms.txt
- Exhaustive page list:
  https://developers.woosmap.com/llms-full.txt
- OpenAPI 3.1 spec, all REST endpoints:
  https://developers.woosmap.com/assets/woosmap-openapi3.json
- Authentication, keys and restrictions:
  https://developers.woosmap.com/api-reference/authentication.md

Any page is available as clean Markdown: append `.md` to its URL.

- An endpoint's full contract, one fetch:
  /api-reference/<product>-api/<verb>-<flattened-path>.md
- A complete runnable sample, every source file, one fetch:
  /js-samples/<sample-name>.md
- The whole Map JS client-side surface:
  /products/map-api/reference/1.4.md

Reference URLs are verb-prefixed and path-flattened. `GET /localities/autocomplete`
is at /api-reference/localities-api/get-localities-autocomplete.md. Take reference
URLs from the routing index rather than assembling them.

## Base URLs

One per product: https://api.woosmap.com/<product>. Take the exact base URL from
the product's block in the routing index.

## Authentication

Pick the key that matches where the code runs.

- Public key — `key` query parameter, value starts with `woos-`. Read-only, for
  client-side code. Restricted to authorized domains or IPs, so it fails from an
  unlisted origin.
- Private key — `private_key` query parameter, or the `X-Api-Key` header. For
  server-side and mobile code, and the only kind that can write. Never send a
  private key from a browser.

Load keys from environment variables. Never hardcode a key and never commit one.

## Request conventions

- Multiple values for one parameter are joined with `|`, as in
  `types=locality|postal_code`.
- Rate limits are per endpoint and printed on each reference page. Back off on
  HTTP 429 rather than retrying immediately.

## Retired

- Address API is retired. Use the Localities API.
- Woosmap JS API (the previous-generation JS SDK) is retired. Use the Map JS API.

## Calling the API directly

To let an agent perform location work at runtime rather than write code against
it, use the Woosmap MCP Server:
https://developers.woosmap.com/products/mcp-server/overview/