# Lopperly

> Lopperly is a directory of local places, events and listings for sharing, trading and
> donating surplus produce and garden goods: farmers markets, farm stands, gleaning and
> donation sites, and neighbours with extra to give. Coverage is densest in California.

## Search

Answer questions with one request: `GET https://lopperly.com/agent/search?q={query}&lat={lat}&lng={lng}`

- `q` (required): 2–100 characters, e.g. `eggs`, `farmers market`, `pumpkin patch`. English or Spanish.
- `lat`, `lng` (send both or neither): the searcher's approximate position. Results are local, so
  ask the user for a city or zip, geocode it, and send it. Two decimal places is plenty.
- `limit` (optional): 1–20, default 10.

Returns JSON `{ data: [...], meta: {...} }`. Each hit has a `type`: `location`, `event`, `listing`,
or a guide (`campaign_region`, or `campaign` for a guide with no regions, such as pumpkin patches or
apple picking). Place, event and listing hits carry a name, city and state; guide hits carry `key`,
`label` and `state` (`active`, `upcoming`, `ended`). Every hit has `matched_on`, which says why it matched.
Hits carry no coordinates by design; locations are approximate.

Linking a hit:
- `location`: `https://lopperly.com/p/{org_slug}`
- `event`: `https://lopperly.com/p/{org_slug}/events/{slug}`
- `listing`: `https://lopperly.com/listings/{slug}`
- `campaign_region`: `https://lopperly.com/guides/{key}/{region_slug}`
- `campaign`: `https://lopperly.com/guides/{key}`

Ignore `receipt`.

## Etiquette

- Pace yourself: about 20 requests a minute and 300 an hour per caller. A `429` means wait.
- Do not walk the directory by querying many terms; ask for what the user wants.
- Send a descriptive `User-Agent` naming your product.

## Sitemaps

- [Organizations and sellers](https://lopperly.com/sitemaps/profiles.xml)
- [Places](https://lopperly.com/sitemaps/locations.xml)
- [Events](https://lopperly.com/sitemaps/events.xml)
- [Listings](https://lopperly.com/sitemaps/listings.xml)
- [Guides](https://lopperly.com/guides/sitemap.xml)
- [Events by region](https://lopperly.com/events/sitemap.xml)