@dromney/mapthis

Open-source location intelligence toolkit. Parse freeform text, HTML, and URLs into geocoded locations; ship with types and React components for rendering maps.

npm install @dromney/mapthis

You'll also want one or more optional peer deps (see Subpath exports):

# pick what you use:
npm install openai js-tiktoken                       # @dromney/mapthis/ai (OpenAI)
npm install @anthropic-ai/sdk js-tiktoken            # @dromney/mapthis/ai (Anthropic)
npm install @googlemaps/google-maps-services-js      # @dromney/mapthis/geocoding
npm install html-to-text                             # @dromney/mapthis/scrape
npm install react react-dom @vis.gl/react-google-maps  # @dromney/mapthis/react

Quick start

import { createLocationParser } from "@dromney/mapthis/ai"
import { createGeocoder } from "@dromney/mapthis/geocoding"
import { createMapGenerator } from "@dromney/mapthis/generate"

const generator = createMapGenerator({
    parser: createLocationParser({ apiKey: process.env.OPENAI_API_KEY! }),
    geocoder: createGeocoder({ provider: "google", apiKey: process.env.GOOGLE_MAPS_KEY! }),
})

const result = await generator.generateFromSource({
    sourceType: "url",
    source: "https://example.com/best-restaurants-tokyo",
})

console.log(result.title)
for (const p of result.places) {
    if (p.data) console.log(p.data.name, p.data.lat, p.data.lng)
    else console.warn("could not geocode", p.input.address, "—", p.error)
}

sourceType accepts "url", "text", or "list". For "list", each newline-separated entry is geocoded directly with no LLM call (and no LLM cost).

Subpath exports

@dromney/mapthis ships a root entry plus focused subpaths so consumers only load what they use.

| Subpath | What it contains | Optional peer deps | |---|---|---| | @dromney/mapthis | Re-exports types + utils (lightweight only) | — | | @dromney/mapthis/types | Zod schemas + TS domain types (PlaceMap, Place, PlaceGroup, Partner, ParsedLocation, Coordinates, …) | — | | @dromney/mapthis/utils | Pure helpers: text, color, numbers, geo, stopwatch | — | | @dromney/mapthis/scrape | getHtmlFromUrl, htmlToText, getTextFromUrl | html-to-text | | @dromney/mapthis/search | createSearchClient (Google Custom Search) | — | | @dromney/mapthis/ai | createLocationParser, createOpenAiBackend, createAnthropicBackend, summarizeText, prompts | openai or @anthropic-ai/sdk, plus js-tiktoken | | @dromney/mapthis/geocoding | createGeocoder (Google Maps) with pluggable GeocodingProvider | @googlemaps/google-maps-services-js | | @dromney/mapthis/generate | createMapGenerator — composes parser + geocoder into a pure orchestrator | — (transitively whatever parser/geocoder use) | | @dromney/mapthis/react | MapProvider, GoogleMapsViewer, PlaceMarker, autofit, browserAutocomplete | react, react-dom, @vis.gl/react-google-maps |

Choosing an LLM backend

createLocationParser accepts either an OpenAI config, an Anthropic config, or a bring-your-own backend implementing the LlmBackend interface.

// OpenAI (default)
createLocationParser({ apiKey: process.env.OPENAI_API_KEY! })
createLocationParser({ provider: "openai", apiKey: ..., model: "gpt-4o-mini" })

// Anthropic
createLocationParser({
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-haiku-4-5-20251001",
})

// Bring-your-own (e.g. an Azure/Bedrock adapter or a deterministic test fake)
createLocationParser({ backend: myCustomBackend })

Both bundled backends implement the same two-stage pipeline: a chunked summarization pass to fit the model's context window, followed by a structured-output call (OpenAI function calling, Anthropic tool use) to extract the location list.

Persisting results

createMapGenerator is intentionally pure — it returns a plain object and never touches a database. Wire the result into your own persistence layer:

const result = await generator.generateFromSource({ sourceType: "url", source: url })

await db.$transaction(async (tx) => {
    const map = await tx.map.create({ data: { title: result.title /* … */ } })
    const group = await tx.placeGroup.create({ data: { mapId: map.id /* … */ } })
    await tx.place.createMany({
        data: result.places.map((p, i) => ({
            mapId: map.id,
            groupId: group.id,
            position: i,
            query: p.input.address,
            description: p.input.description,
            name: p.data?.name,
            address: p.data?.address,
            lat: p.data?.lat,
            lon: p.data?.lng,
            provider: p.data?.provider,
            providerId: p.data?.providerId,
            error: p.error,
            locationPromptVersion: result.locationPromptVersion,
            summaryPromptVersion: result.summaryPromptVersion,
        })),
    })
})

Error handling

Every error thrown by the package extends MapthisError (@dromney/mapthis/types). Domain-specific subclasses let callers handle the failure modes that matter to their UX:

| Class | Subpath | When | |---|---|---| | InvalidUrlError, ScrapeError | /scrape | URL was unreachable or returned non-HTML | | NoSearchResultsError, SearchError | /search | Google CSE returned zero usable results | | NoLocationsFoundError, AiInputLengthError, AiOutputLengthError, AiResponseJsonError, InvalidJsonSchemaError, SummarizeTextError, AiError | /ai | LLM stage failed | | GeocodingError | /geocoding | Geocoder threw (per-input failures resolve, not throw) |

Per-input geocoder failures are not thrown — geocodeMany returns a PlaceQueryResult with data: null and error: string so one bad address can't fail an entire batch.

Design principles

• No process.env reads. All secrets are passed to factory functions by the consumer. Keeps the package portable and testable.
• Framework-agnostic. Core modules are pure TypeScript. React components live behind the @dromney/mapthis/react subpath so server-only consumers skip them entirely.
• Plain domain types. Hand-rolled TS with matching Zod schemas. Consumers aren't locked to a particular ORM — write adapter functions between your DB models and these types in your app.
• Optional peer deps for heavy things. Every SDK is an optional peer dependency. Install only what the subpaths you use need.

License

Apache 2.0 — see LICENSE.