@mw-kit/mw-geocoding

SDK Node.js público para consumir as operações públicas de mapas da API mw-geocoding.

O pacote expõe a classe MwGeocodingClient como superfície pública inicial. O runtime mínimo contratado é Node.js >=20, usando fetch global ou uma implementação customizada informada nas opções.

O import público é feito pelo pacote root:

import { MwGeocodingClient } from '@mw-kit/mw-geocoding'

const client = new MwGeocodingClient({
  apiKey: 'mwg_example.key',
  baseUrl: 'https://api.example.test',
})

apiKey é a credencial runtime usada nas chamadas HTTP para a API mw-geocoding. Ela é independente de tokens npm usados por mantenedores para publicar o pacote.

As operações retornam resultado discriminado por success:

const result = await client.coordinate(
  {
    city: 'São Paulo',
    country: 'BR',
    street: 'Praça da Sé',
  },
  {
    language: 'pt-BR',
    requestId: 'request-123',
  },
)

if (result.success) {
  console.log(result.data.coordinates)
} else {
  console.error(result.error.kind, result.error.message)
}

Instalação

O pacote @mw-kit/mw-geocoding é publicado como pacote npm público no registry npm oficial. Consumidores normais não precisam configurar .npmrc com _authToken nem informar NPM_TOKEN para instalar o pacote.

pnpm add @mw-kit/mw-geocoding

npm install @mw-kit/mw-geocoding

NPM_TOKEN é um token npm usado pelo pipeline de publicação. Ele não autentica download público normal do pacote, não é API key runtime da API, não deve ser usado como valor de apiKey e não deve ter valor real gravado em arquivos versionados.

Operações

coordinate

const result = await client.coordinate({
  city: 'São Paulo',
  country: 'BR',
  minimumConfidence: 'regular',
  number: 1,
  postalCode: '01001-000',
  state: 'SP',
  street: 'Praça da Sé',
  strategies: ['database', 'mapbox'],
})

if (result.success) {
  console.log(result.data.coordinates.lat, result.data.coordinates.lng)
}

address

const result = await client.address({
  coordinates: {
    lat: -23.55052,
    lng: -46.633308,
  },
  minimumConfidence: 'high',
  strategies: ['mapbox', 'google'],
})

if (result.success) {
  console.log(result.data.address.cityName)
}

postalCode

const result = await client.postalCode({
  postalCode: '01001-000',
  requiredFields: ['ibgeCode'],
  strategies: ['database', 'brasilapi', 'viacep'],
})

if (result.success) {
  console.log(result.data.formattedPostalCode, result.data.cityName)
}

route

const result = await client.route({
  coordinates: [
    { lat: -23.55052, lng: -46.633308 },
    { lat: -23.561414, lng: -46.655881 },
  ],
  geometryFormat: 'encoded',
  strategies: ['osrm'],
})

if (result.success) {
  console.log(result.data.distance, result.data.duration)
}

matrix

const result = await client.matrix({
  coordinates: [
    { lat: -23.55052, lng: -46.633308 },
    { lat: -23.561414, lng: -46.655881 },
    { lat: -23.567, lng: -46.648 },
  ],
  optimizeBy: 'duration',
  startIndex: 0,
  strategies: ['osrm', 'google-distance'],
})

if (result.success) {
  console.log(result.data.origins)
}

O contrato público da API usado pelo SDK fica em ../api/openapi/. O client Node.js não importa módulos internos de ../api/src/.