Context

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:

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)")
        }
    }
}

[Radar getContextWithCompletionHandler:^(RadarStatus status, CLLocation * _Nullable location, RadarContext * _Nullable context) {
    if (status == RadarStatusSuccess && context) {
        // Geofences
        NSLog(@"Geofences: %lu", (unsigned long)context.geofences.count);
        for (RadarGeofence *geofence in context.geofences) {
            NSLog(@"  - %@", geofence.__description);
        }
        
        // Place
        if (context.place) {
            NSLog(@"Place: %@", context.place.name);
            NSLog(@"Categories: %@", [context.place.categories componentsJoinedByString:@", "]);
        }
        
        // Country
        if (context.country) {
            NSLog(@"Country: %@ (%@)", context.country.name, context.country.code);
            if (context.country.flag) {
                NSLog(@"Flag: %@", context.country.flag);
            }
        }
        
        // State
        if (context.state) {
            NSLog(@"State: %@ (%@)", context.state.name, context.state.code);
        }
        
        // DMA
        if (context.dma) {
            NSLog(@"DMA: %@ (%@)", context.dma.name, context.dma.code);
        }
        
        // Postal code
        if (context.postalCode) {
            NSLog(@"Postal code: %@", context.postalCode.name);
        }
    }
}];

Context for Specific Location

Get context for any geographic coordinate:

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)")
        }
    }
}

CLLocation *location = [[CLLocation alloc] initWithLatitude:40.7128 longitude:-74.0060];

[Radar getContextForLocation:location completionHandler:^(RadarStatus status, CLLocation * _Nullable location, RadarContext * _Nullable context) {
    if (status == RadarStatusSuccess && context) {
        NSLog(@"Location: %f, %f", location.coordinate.latitude, location.coordinate.longitude);
        
        if (context.place) {
            NSLog(@"At place: %@", context.place.name);
        }
        
        if (context.country) {
            NSLog(@"In country: %@", context.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

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")
    }
}

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")
        }
    }
}

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")
        }
    }
}

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

Check for nil

Always check if context properties are nil before using them:

if let context = context, let place = context.place {
    // Use place
}

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
}

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

Getting Started

Core Features

Location Services

Configuration

Advanced

Migration & Support

Overview

What’s Included

Geofences

Place

Regions

No Tracking

Get Context

Context for Current Location

Context for Specific Location

Context Properties

Geofences

Place

Country

State

DMA (Designated Market Area)

Postal Code

Use Cases

Privacy Considerations

Comparison with Track API

Error Handling

Best Practices

Learn More

Context API

Geofences

Places

Regions

​Overview

​What’s Included

Geofences

Place

Regions

No Tracking

​Get Context

​Context for Current Location

​Context for Specific Location

​Context Properties

​Geofences

​Place

​Country

​State

​DMA (Designated Market Area)

​Postal Code

​Use Cases

​Privacy Considerations

​Comparison with Track API

​Error Handling

​Best Practices

​Learn More

Context API

Geofences

Places

Regions

Overview

What’s Included

Get Context

Context for Current Location

Context for Specific Location

Context Properties

Geofences

Place

Country

State

DMA (Designated Market Area)

Postal Code

Use Cases

Privacy Considerations

Comparison with Track API

Error Handling

Best Practices

Learn More