go get github.com/navvo/navvo-go

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

c, err := navvo.New("")                    // يستخدم ‎$NAVVO_API_KEY‎
c, err := navvo.New("nvvo_your_key_here")  // صريح

package main

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

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

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

    // ترميز جغرافي أمامي — تُحوّل الإحداثيات النصّية إلى أرقام نيابةً عنك.
    hits, err := c.Geocode(ctx, "مستشفى العبدلي، عمّان", &navvo.GeocodeOptions{Limit: 5})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(hits[0].Lat, hits[0].Lng, hits[0].DisplayName)

    // خطّط مسارًا — تمرّر {Lat, Lng} وتتولّى المكتبة ترتيب lon/lat على الشبكة.
    plan, err := c.Route(ctx, navvo.RoutePlanRequest{
        Locations: []navvo.LatLng{
            {Lat: 31.95, Lng: 35.91, Name: "أ"},
            {Lat: 31.99, Lng: 35.95, Name: "ب"},
        },
        Costing: "auto",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("الزمن المقدّر (ثوانٍ):", plan.Trip().Summary.Time)

    // فكّ ترميز المسار (polyline6) إلى نقاط.
    line := plan.Geometry()
    fmt.Println("عدد نقاط الشكل:", len(line))

    // إضافات حيّة تراعي الظروف.
    wx, _ := c.WeatherPoint(ctx, 31.95, 35.91, "metric")
    fmt.Println(wx.Temperature, wx.Unit)
}

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, "مستشفى العبدلي، عمّان", nil)
if err != nil {
    var rl *navvo.RateLimitError
    var scope *navvo.ScopeError
    switch {
    case errors.As(err, &rl):
        log.Printf("تم تجاوز الحدّ، أعد المحاولة بعد %v", rl.RetryAfter)
    case errors.As(err, &scope):
        log.Printf("مشكلة نطاق/حصّة: %s (ينقص %s)", scope.Reason, scope.Scope)
    case errors.Is(err, navvo.ErrServiceUnavailable):
        log.Print("مزوّد الترميز الجغرافي متوقّف — استخدم بديلًا")
    default:
        return err
    }
}

res, err := c.Search(ctx, "pharmacy", &navvo.SearchOptions{
    Near:      &navvo.LatLng{Lat: 31.9539, Lng: 35.9106}, // رتّب الأماكن الأقرب أولًا
    RadiusKm:  3,                                         // كلٌّ من RadiusKm و SortDistance يحتاج 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) // لاستخدامه مع SendSearchEvent
for i, p := range res.Places.Items {
    // تكون DistanceKm و Highlight بقيمة nil حين لا تنطبقان، وتكون ImageURL فارغة حين لا توجد صورة.
    fmt.Println(res.Places.Position(i), p.NameEn, p.DistanceKm, p.ImageURL, p.Promoted)
}
fmt.Println(res.DidYouMean, len(res.Suggestions)) // عند انعدام النتائج فقط: تصحيح إملائي وأماكن شائعة

c.Search(ctx, "rumi caf", &navvo.SearchOptions{Mode: navvo.SearchModeTypeahead})                              // أثناء الكتابة
c.Search(ctx, "quiet place to work with good coffee", &navvo.SearchOptions{Semantic: navvo.SearchSemanticOn}) // المطابقة حسب المعنى
c.Search(ctx, "pharmacy", &navvo.SearchOptions{Analytics: navvo.Bool(false)})                                 // أبقِ هذا الاستدعاء خارج التحليلات
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 حين لا يطابق أي اسم، أو حين لم تُطلب الإبرازات
        for _, seg := range navvo.ParseHighlight(p.Highlight.NameEn) {
            fmt.Print(seg.Text, seg.Match)
        }
    }
}

res, err := c.Search(ctx, "مقهى", &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 { // اليوم، بتوقيت الأردن
        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 و Address بالعربية

session := navvo.NewSearchSessionID() // واحد لكل جلسة مستخدم، وبموافقة المستخدم فقط
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) // النتيجة التي فتحها المستخدم

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]