Bibliotecas cliente e Postman

O que está disponível

Cada uma tem um método por operação da API, com o nome da referência da API, envia a sua chave no cabeçalho X-NWays-Api-Key, e transforma as respostas de erro num erro que contém o estado HTTP, a reason (API_KEY_HTTP_REFERRER_BLOCKED, RATE_LIMIT_EXCEEDED…) e os segundos de Retry-After. Para mapas em páginas web e aplicações, use os SDK Maps web, Android e iOS, que incluem as mesmas chamadas.

Exemplos

import { NWaysClient, ApiError } from '@nways/client'

const nways = new NWaysClient({ apiKey: process.env.NWAYS_API_KEY! })
try {
  const { results } = await nways.geocode({ q: 'Allen Avenue, Ikeja', limit: 3 })
  console.log(results[0]?.name, results[0]?.location.coordinates)
} catch (e) {
  if (e instanceof ApiError && e.status === 429) console.log(`Repetir dentro de ${e.retryAfter} s`)
  else throw e
}

import os
from nways_maps import ApiError, Client

nways = Client(api_key=os.environ["NWAYS_API_KEY"])
try:
    answer = nways.geocode(q="Allen Avenue, Ikeja", limit=3)
    print(answer["results"][0]["name"])
except ApiError as e:
    print(e.status, e.reason, e.retry_after)

import ng.nways.client.ApiError
import ng.nways.client.NWaysClient

val nways = NWaysClient(apiKey = System.getenv("NWAYS_API_KEY"))
// As chamadas são bloqueantes: numa aplicação, execute-as em Dispatchers.IO.
try {
    val answer = nways.geocode(q = "Allen Avenue, Ikeja", limit = 3)
    println(answer.results.firstOrNull()?.name)
} catch (e: ApiError) {
    println("${e.status} ${e.reason}")
}

import NWaysClient

let nways = NWaysClient(apiKey: "A_SUA_CHAVE_API")
do {
    let answer = try await nways.geocode(q: "Allen Avenue, Ikeja", limit: 3)
    print(answer.results.first?.name ?? "nenhum resultado")
} catch let e as NWaysError {
    print(e.status, e.reason ?? "", e.message)
}

Postman

Experimente cada pedido sem escrever código:

1. Transfira a coleção N-Ways Maps Platform.
2. No Postman, escolha Import e selecione o ficheiro.
3. Nas Variables da coleção, dê a apiKey uma chave restrita ao endereço IP do seu computador. baseUrl é https://nways.ng.
4. Abra um pedido e carregue em Send.

Também funciona no Insomnia, no Bruno e nas outras ferramentas que importam coleções Postman ou ficheiros OpenAPI.

Ficheiros OpenAPI

A referência da API, as bibliotecas cliente e a coleção Postman são todas produzidas a partir de dois ficheiros OpenAPI 3.1, que pode usar com qualquer ferramenta OpenAPI para gerar um cliente noutra linguagem, simular a API nos seus testes ou validar pedidos:

• partner-v1.openapi.yaml: mapas, geocodificação, lugares, percursos, tarifas e trânsito.
• partner-fleet.openapi.yaml: seguimento de frota, webhooks, fluxo de trânsito e pacotes offline.

Versões

As bibliotecas cliente seguem a API: a versão 1 de um cliente chama a versão 1 da API (/maps/v1), e apenas ganha métodos e campos. Os tipos gerados aceitam campos que ainda não conhecem, por isso uma API mais recente nunca estraga um cliente mais antigo. Como funcionam as versões

Licença

As quatro bibliotecas cliente são de código aberto sob a licença Apache 2.0 (Apache-2.0), Copyright 2026 N-WAYS LIMITED; cada pacote contém os seus ficheiros LICENSE e NOTICE. A licença abrange apenas o código: os mapas e os dados do N-Ways continuam © contribuidores do OpenStreetMap sob a Open Database Licence (ODbL), com a atribuição mostrada onde quer que apareçam.