Locations and Weather

Here and now

Location

Critical Moments offers two forms of location: system and approximate.

System location

Most location lookups uses the system location framework (onboard GPS and cellular trilateration). System location is used for any location parameter without _approx in the name. When using these be aware:

• Location properties will return nil if the user has not granted permission to access to location. Your app should manage requesting this permission. Please follow this guide from Apple. Your conditions should consider the possibility of a nil response. You can check if they have granted permision via the location_permission property.

• The SDK will initiate new location request at most once every 5 minutes to save battery. If your app (or the system) is requesting location more often it will use the latest cached value. As a result, the location may be up to 5 minutes stale.

• Evaluating conditions with location properties will show a "location services" indicator on the user's device.

Approximate Location

Critical Moments provides a Geo-IP lookup service for inferring approximate location. Things to be aware of using approximate:

• Unlike system location, approximate location can be used without the system location permission

• Requests are being made to a Critical Moments server with the end user's IP when using the approximate location. Please ensure your terms of service and privacy policy allows this before using Geo-IP data.

• Approximate location will not work when offline.

• Approximate location may be incorrect as IPs can move between cities/regions over time. Approximate location should only be used for scenarios where incorrect data is tolerable.

• The lat/long returned should be considered approximate, and not used for use cased where precision is needed.

• Approximate location is cached for 20 minutes

• Approximate location uses GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

Rate Limit: During the private beta, approximate location requests have a soft-limit of 10,000 requests per month per app . Need more? Contact us! Repeatedly or excessively exceeding your limit without contacting us for a higher limit, may result in approximate location services being disabled for that client/app.

Reverse Geocoding / Place Names

"Reverse geocoding" looking up the name of a place, given a location (lat/long). Critical Moments offers helpful reverse geocoding helpers to get the city name, region name (state/province), and country name of a user's location. Some technical notes on these:

• Reverse geocoding results (city, region, and country), are cached for the entirety of the user's session.

• Reverse geocoding results may be nil if the device is not currently in a city/province/state/country (example, on the ocean).

Weather Usage Restrictions

Critical Moments allows you to easily access the weather at your user's current location.

The weather properties built into Critical Moments use an external weather service to provide local weather data. There are restructions about how you use this data:

• Rate Limit: During the private beta, weather requests have a soft-limit of 3000 requests per month per app . Need more? Contact us! Repeatedly or excessively exceeding your limit without contacting us for a higher limit, may result in weather services being disabled for that client/app.

• Usage Limits: You can use our weather data to make conditional decisions in your app, but you may not build an app or service which directly displays weather data to your users or any third parties. Violatiung these usage restrictions may result in weather services being disabled for the violoating app/client.

  • Acceptable use examples:

    • A travel app which features a section called "Escape the cold" with Caribbean vacations, when the temperature in the users location is less than -5 celsius

    • An in insurance app that displays a promotion for "Add flood coverage to your home plan" when it's raining.

    • A food delivery app which "Stay dry, order delivery" header when it's raining

  • Unacceptable use examples:

    • A UI interface element which shows the user the temperature in the user's location to the user

    • A UI interface element which shows the current weather conditions (snow, rain) to the user in any form (textual, icon, etc)

Technical Notes

• Weather is cached for 20 minutes.

• Any weather value may return nil (or "unknown"), if the user's location can't be found, if they don't have a network connection, or weather data is not available for that location. Please ensure you conditionals can handle nil values for weather properties gracefully.

• Weather properties each have 2 options, one using system location, and another using approximate location. System location is less likely to be incorrect (using GPS lat/long instead of location inferred from IP), but will fail when the user has not given the app location permissions and will result in the location-privacy indicator appearing at the top of their phone. Consider conditionally using location_permission and the ternary operator to check if the user has granted location permission, falling back to approximate location; for example for temperature: location_permission ? weather_temperature : weather_approx_location_temperature

• We add a random offset to location when using the system location, before leaving the device (up to 1km, avg 500m). This prevents precise user location being sent to our servers, and 1km is close enough for weather data.

• Privacy impact: using weather properties requires making an external web services call to Critical Moments to fetch weather data. We make this as private as possible, only transmitting the minimal amount of data needed to provide weather data. Techically the process involves:

  • When fetching, Critical Moments will have access to the data passed, including the end user's latitude, longitude, and IP address, and the app's ID and API key. Critical Moments logs may capture this data in short term logs, but all user-level data will be deleted in time (currently 7 days).

  • Aggregate usage data is tracked by Critical Moments long term at the app level to enforce rate limits; this data does not include user location data or user IP addresses.

  • Critical Moments will call a third party weather service with latitude and longitude to retrieve weather data, but no data tying the location to a given user is passed to that service (including the user's IP address or app ID).

  • Please ensure your terms of service and privacy policy allows this before using weather data.

• Weather data is currently provided from Apple Weather, and includes data from a variety of data sources.

Condidtion Values

The "condition" property may have the following values:

All Weather Condition String Values

BlowingDust
Clear
Cloudy
Foggy
Haze
MostlyClear
PartlyCloudy
Smoky
Breezy
Windy
Drizzle
HeavyRain
IsolatedThunderstorms
Rain
SunShowers
ScatteredThunderstorms
StrongStorms
Thunderstorms
Frigid
Hail
Hot
Flurries
Sleet
Snow
SunFlurries
WintryMix
Blizzard
BlowingSnow
FreezingDrizzle
FreezingRain
Hurricane
TropicalStorm