Context

Get comprehensive location context including places, geofences, regions, and neighborhoods

Radar’s Context API provides rich location context for any geographic coordinate, including nearby places, active geofences, country, state, DMA, and postal code information.

Overview

The Context API returns location information without requiring device or user identifiers, making it ideal for privacy-conscious applications and server-side integrations.

What’s Included

Geofences

All geofences containing the location

Place

The place at the location, if any

Regions

Country, state, DMA, and postal code

No Tracking

No device or user identifiers sent

Get Context

Context for Current Location

Get context for the device’s current location:

Swift

Radar.getContext { status, location, context in
    if status == .success, let context = context {
        // Geofences
        print("Geofences: \(context.geofences.count)")
        context.geofences.forEach { geofence in
            print("  - \(geofence.__description)")
        }
        
        // Place
        if let place = context.place {
            print("Place: \(place.name)")
            print("Categories: \(place.categories.joined(separator: ", "))")
        }
        
        // Country
        if let country = context.country {
            print("Country: \(country.name) (\(country.code))")
            if let flag = country.flag {
                print("Flag: \(flag)")
            }
        }
        
        // State
        if let state = context.state {
            print("State: \(state.name) (\(state.code))")
        }
        
        // DMA
        if let dma = context.dma {
            print("DMA: \(dma.name) (\(dma.code))")
        }
        
        // Postal code
        if let postalCode = context.postalCode {
            print("Postal code: \(postalCode.name)")
        }
    }
}

Context for Specific Location

Get context for any geographic coordinate:

Swift

let location = CLLocation(latitude: 40.7128, longitude: -74.0060)

Radar.getContext(location: location) { status, location, context in
    if status == .success, let context = context {
        print("Location: \(location?.coordinate.latitude ?? 0), \(location?.coordinate.longitude ?? 0)")
        
        if let place = context.place {
            print("At place: \(place.name)")
        }
        
        if let country = context.country {
            print("In country: \(country.name)")
        }
    }
}

Context Properties

The RadarContext object provides comprehensive location information:

Geofences

An array of all geofences that contain the location:

Radar.getContext { status, location, context in
    if let geofences = context?.geofences {
        for geofence in geofences {
            print("Geofence ID: \(geofence._id)")
            print("Description: \(geofence.__description)")
            print("Tag: \(geofence.tag ?? "None")")
            print("External ID: \(geofence.externalId ?? "None")")
            
            if let metadata = geofence.metadata {
                print("Metadata: \(metadata)")
            }
            
            if let operatingHours = geofence.operatingHours {
                print("Operating hours available")
            }
        }
    }
}

Place

The place at the location, if any:

Radar.getContext { status, location, context in
    if let place = context?.place {
        print("Place ID: \(place._id)")
        print("Name: \(place.name)")
        print("Categories: \(place.categories)")
        
        if let chain = place.chain {
            print("Chain: \(chain.name) (\(chain.slug))")
            if let chainMetadata = chain.metadata {
                print("Chain metadata: \(chainMetadata)")
            }
        }
        
        if let group = place.group {
            print("Group: \(group)")
        }
        
        if let address = place.address {
            print("Address: \(address.formattedAddress ?? "")")
        }
        
        // Check place properties
        if place.isChain("starbucks") {
            print("This is a Starbucks")
        }
        
        if place.hasCategory("restaurant") {
            print("This is a restaurant")
        }
    } else {
        print("Not at a known place")
    }
}

Country

Country information for the location:

Radar.getContext { status, location, context in
    if let country = context?.country {
        print("Country ID: \(country._id)")
        print("Name: \(country.name)")
        print("Code: \(country.code)")
        print("Type: \(country.type)")
        
        if let flag = country.flag {
            print("Flag: \(flag)")
        }
        
        // Jurisdiction properties (for fraud detection)
        print("Allowed: \(country.allowed)")
        print("Passed: \(country.passed)")
        print("Expected: \(country.expected)")
        print("In exclusion zone: \(country.inExclusionZone)")
        print("In buffer zone: \(country.inBufferZone)")
        print("Distance to border: \(country.distanceToBorder)m")
    }
}

State

State or province information:

Radar.getContext { status, location, context in
    if let state = context?.state {
        print("State ID: \(state._id)")
        print("Name: \(state.name)")
        print("Code: \(state.code)")
        print("Type: \(state.type)")
        
        // Jurisdiction properties
        print("Allowed: \(state.allowed)")
        print("Distance to border: \(state.distanceToBorder)m")
    }
}

DMA (Designated Market Area)

Media market information:

Radar.getContext { status, location, context in
    if let dma = context?.dma {
        print("DMA ID: \(dma._id)")
        print("Name: \(dma.name)")
        print("Code: \(dma.code)")
    }
}

Postal Code

Postal code or ZIP code information:

Radar.getContext { status, location, context in
    if let postalCode = context?.postalCode {
        print("Postal code ID: \(postalCode._id)")
        print("Code: \(postalCode.name)")
    }
}

Use Cases

1. Geofence Detection

   Detect when a user enters specific geofences without continuous tracking:

   Radar.getContext { status, location, context in
       let isInDeliveryZone = context?.geofences.contains { geofence in
           geofence.tag == "delivery-zone"
       } ?? false
       
       if isInDeliveryZone {
           print("User is in delivery zone")
       }
   }
   
2. Location Verification

   Verify a user’s location for compliance or fraud prevention:

   Radar.getContext { status, location, context in
       if let country = context?.country {
           if country.code == "US" && country.passed {
               print("User verified in United States")
           }
       }
   }
   
3. Place Detection

   Determine if a user is at a specific type of location:

   Radar.getContext { status, location, context in
       if let place = context?.place {
           if place.hasCategory("airport") {
               print("User is at an airport")
           }
       }
   }
   
4. Regional Customization

   Customize app experience based on location:

   Radar.getContext { status, location, context in
       if let state = context?.state {
           // Show state-specific content
           print("Showing content for \(state.name)")
       }
       
       if let dma = context?.dma {
           // Target ads by media market
           print("DMA: \(dma.name)")
       }
   }
   

Privacy Considerations

The Context API is designed with privacy in mind:

No User Tracking: Context requests do not send device identifiers, user IDs, or other personally identifiable information to the server.

Use the Context API instead of full tracking when you only need occasional location context without continuous monitoring.

Comparison with Track API

Feature	Context API	Track API
Returns geofences	✅ Yes	✅ Yes
Returns places	✅ Yes	✅ Yes
Returns regions	✅ Yes	✅ Yes
Sends device ID	❌ No	✅ Yes
Sends user ID	❌ No	✅ Yes
Generates events	❌ No	✅ Yes
Updates user state	❌ No	✅ Yes
Background tracking	❌ No	✅ Yes

Use the Context API for one-time location queries. Use the Track API for continuous location monitoring and event generation.

Error Handling

Handle errors gracefully with status codes:

Radar.getContext { status, location, context in
    switch status {
    case .success:
        print("Context retrieved successfully")
        
    case .errorLocation:
        print("Could not determine location")
        
    case .errorPermissions:
        print("Location permissions not granted")
        
    case .errorNetwork:
        print("Network error occurred")
        
    case .errorRateLimit:
        print("Rate limit exceeded")
        
    default:
        print("Error: \(Radar.stringForStatus(status))")
    }
}

Best Practices

1. Check for nil

   Always check if context properties are nil before using them:

   if let context = context, let place = context.place {
       // Use place
   }
   
2. Handle empty arrays

   Geofences array may be empty if the location isn’t in any geofences:

   if let geofences = context?.geofences, !geofences.isEmpty {
       // Process geofences
   }
   
3. Respect rate limits

   The Context API is subject to rate limits. Don’t call it too frequently:

   // Good: Call on user action
   button.addTarget { 
       Radar.getContext { status, location, context in
           // Handle context
       }
   }
   
   // Bad: Call repeatedly in a loop
   // Don't do this!
   

Learn More

Context API

Explore the complete Context API reference

Geofences

Learn about geofencing capabilities

Places

Understand place search and detection

Regions

Explore region data model