go get github.com/navvo/navvo-go

import navvo "github.com/navvo/navvo-go"

c, err := navvo.New("")                    // uses $NAVVO_API_KEY
c, err := navvo.New("nvvo_your_key_here")  // explicit

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    navvo "github.com/navvo/navvo-go"
)

func main() {
    c, err := navvo.New("") // reads NAVVO_API_KEY
    if err != nil {
        log.Fatal(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    // Forward geocode — string coordinates are parsed to numbers for you.
    hits, err := c.Geocode(ctx, "Abdali Hospital, Amman", &navvo.GeocodeOptions{Limit: 5})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(hits[0].Lat, hits[0].Lng, hits[0].DisplayName)

    // Plan a route — you pass {Lat, Lng}; the SDK serialises lon/lat on the wire.
    plan, err := c.Route(ctx, navvo.RoutePlanRequest{
        Locations: []navvo.LatLng{
            {Lat: 31.95, Lng: 35.91, Name: "A"},
            {Lat: 31.99, Lng: 35.95, Name: "B"},
        },
        Costing: "auto",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("ETA seconds:", plan.Trip().Summary.Time)

    // Decode the leg polyline (polyline6) into points.
    line := plan.Geometry()
    fmt.Println("shape points:", len(line))

    // Live, condition-aware extras.
    wx, _ := c.WeatherPoint(ctx, 31.95, 35.91, "metric")
    fmt.Println(wx.Temperature, wx.Unit, "·", *wx.AQICategory)
}

c, err := navvo.New(
    "",
    navvo.WithBaseURL("https://navvo.io/api/v1"),
    navvo.WithTimeout(15*time.Second),
    navvo.WithUserAgent("acme-dispatch/2.3"),
    navvo.WithRetry(navvo.RetryConfig{
        Retries: 3, BaseDelay: 500 * time.Millisecond, Factor: 2, Jitter: true, MaxDelay: 20 * time.Second,
    }),
)

amman := navvo.LatLng{Lat: 31.9539, Lng: 35.9106}
box := navvo.BBox{West: 35.85, South: 31.92, East: 35.98, North: 32.02}

hits, err := c.Geocode(ctx, "Abdali Hospital, Amman", nil)
if err != nil {
    var rl *navvo.RateLimitError
    var scope *navvo.ScopeError
    switch {
    case errors.As(err, &rl):
        log.Printf("rate limited, retry after %v", rl.RetryAfter)
    case errors.As(err, &scope):
        log.Printf("scope/quota problem: %s (missing %s)", scope.Reason, scope.Scope)
    case errors.Is(err, navvo.ErrServiceUnavailable):
        log.Print("geocoder upstream is down — fall back")
    default:
        return err
    }
}

res, err := c.Search(ctx, "pharmacy", &navvo.SearchOptions{
    Near:      &navvo.LatLng{Lat: 31.9539, Lng: 35.9106}, // rank nearer places higher
    RadiusKm:  3,                                         // both RadiusKm and SortDistance need Near
    Sort:      navvo.SearchSortDistance,
    OpenNow:   navvo.Bool(true),
    MinRating: 4,
    Amenities: []string{"wheelchair-accessible-entrance"},
    Facets:    []navvo.SearchFacet{navvo.SearchFacetCategory, navvo.SearchFacetAmenities},
    Highlight: navvo.Bool(true),
})
if err != nil {
    return err
}
fmt.Println(res.QueryID) // for SendSearchEvent
for i, p := range res.Places.Items {
    // DistanceKm and Highlight are nil when they do not apply; ImageURL is "" without a picture.
    fmt.Println(res.Places.Position(i), p.NameEn, p.DistanceKm, p.ImageURL, p.Promoted)
}
fmt.Println(res.DidYouMean, len(res.Suggestions)) // zero results only: a spelling fix, popular places

c.Search(ctx, "rumi caf", &navvo.SearchOptions{Mode: navvo.SearchModeTypeahead})                              // as the user types
c.Search(ctx, "quiet place to work with good coffee", &navvo.SearchOptions{Semantic: navvo.SearchSemanticOn}) // meaning-based matching
c.Search(ctx, "pharmacy", &navvo.SearchOptions{Analytics: navvo.Bool(false)})                                 // keep this call out of analytics
c.SearchSuggestions(ctx, "pha", &navvo.SearchSuggestionsOptions{Limit: 6})                                    // GET /search/suggestions
c.SimilarPlaces(ctx, navvo.SimilarPlacesOptions{Slug: "jordan-museum-994700", Limit: 6})                      // GET /search/similar

for _, p := range res.Places.Items {
    if p.Highlight != nil { // nil when no name matched, or highlights were not requested
        for _, seg := range navvo.ParseHighlight(p.Highlight.NameEn) {
            fmt.Print(seg.Text, seg.Match)
        }
    }
}

res, err := c.Search(ctx, "cafe", &navvo.SearchOptions{
    Near:  &navvo.LatLng{Lat: 31.9539, Lng: 35.9106},
    Price: []int{1, 2},
})
if err != nil {
    return err
}
for _, p := range res.Places.Items {
    fmt.Println(p.NameEn, p.CategoryName, p.PriceRange, p.PriceLevel, p.ReviewCount, p.Address, p.Area, p.Highlights)
    if p.Hours != nil { // today, in Jordan time
        fmt.Println(p.Hours.State, p.Hours.ClosesAt, p.Hours.OpensAt, p.Hours.OpensDay)
    }
}
c.SimilarPlaces(ctx, navvo.SimilarPlacesOptions{Slug: "jordan-museum-994700", Locale: "ar"}) // CategoryName and Address in Arabic

session := navvo.NewSearchSessionID() // one per end-user session, only with the user's consent
res, err := c.Search(ctx, "rumi cafe", &navvo.SearchOptions{Session: session})
if err != nil || len(res.Places.Items) == 0 {
    return err
}
hit, position := res.Places.Items[0], res.Places.Position(0) // the result the user opened

c.SendSearchEvent(ctx, navvo.SearchEvent{
    QueryID: res.QueryID, Type: navvo.SearchEventClick, PlaceID: hit.ID, Position: position,
})
c.SendSearchEvent(ctx, navvo.SearchEvent{
    QueryID: res.QueryID, Type: navvo.SearchEventConversion, Name: navvo.SearchEventDirections,
    PlaceID: hit.ID, Position: position,
})

go get github.com/navvo/[email protected]