Getting Started with the Numerous REST API

This post is intended as a short, simple guide intended to help you get started using the Numerous REST API using cURL.

1. Find Your API Key

In the Numerous app, tap menu > Settings > Developer Info.

2. Create a new metric

In the app, tap the “+” tile. For this example, we'll create a metric called “Sam’s Balance”

3. Get the new metric's ID

From a command line (don’t forget the colon after your API key!):

curl -u {apiKey}: https://api.numerousapp.com/v1/users/me/metrics

You should get output that looks like this:

[
    {
        "id": "4707354896543463485",
        "ownerId": "718",
        "updated": "2014-07-02T11:56:54.110Z",
        "label": "Hudson's Balance",
        "description": "Hudson's allowance account balance",
        "photoURL": "https://api.numerousapp.com/v1/metrics/4707354896543463485/photo",
        "kind": "currency",
        "value": 27.3055,
        "units": "",
        "unit": "",
        "private": true,
        "writeable": true,
        "subscriberCount": 1,
        "currencySymbol": "$",
        "links": {
            "self": "https://api.numerousapp.com/metrics/4707354896543463485",
            "web": "http://n.numerousapp.com/m/zrkajs7inrnh"
        }
    },
    {
        "id": "37803412356902024",
        "ownerId": "718",
        "updated": "2014-08-30T15:30:28.162Z",
        "label": "Sam's Balance",
        "description": "Sam's allowance account balance",
        "photoURL": "https://api.numerousapp.com/v1/metrics/37803412356902024/photo",
        "kind": "currency",
        "value": 0,
        "units": "",
        "unit": "",
        "private": true,
        "writeable": true,
        "subscriberCount": 1,
        "links": {
            "self": "https://api.numerousapp.com/metrics/37803412356902024",
            "web": "http://n.numerousapp.com/m/aclaksjk10o"
        }
    },
    ...
]

We can see that the metric with the label “Sam’s Balance” was created with an id of "37803412356902024".

4. Update the metric with a new value.

You do this not by updating the Metric itself, but by creating a new Event for it. Again from a command line, do this:

curl -u {apiKey}: https://api.numerousapp.com/v1/metrics/37803412356902024/events -d '{"value": 99.99}'

and you should get a response something like this:

{
    "id": "4189887676545784498",
    "metricId": "37803412356902024",
    "authorId": "81726615231635221",
    "updated": "2014-08-30T14:07:43.250Z",
    "value": 99.99
}

5. Success!

If you look at the number in the app, you’ll see that it’s been updated with the new value.

Of course there’s a lot more you can do with the Numerous REST API so I encourage you to browse through the documentation. In a future post I’ll show how to do this and more using PHP.

iOS 8 Preview: HealthKit

This is the third in a series of articles previewing iOS 8-specific features coming to Numerous.

If you haven’t noticed, we’re pretty psyched about Apple’s upcoming iOS 8. Numbers in the Today tab of Notification Center? Check. Anonymous iCloud sign-in? Check. Next up is HealthKit.

What’s HealthKit?

Apple announced HealthKit at WWDC 2014, describing it thusly:

HealthKit allows apps that provide health and fitness services to share their data with the new Health app and with each other. A user’s health information is stored in a centralized and secure location and the user decides which data should be shared with your app.

At first glance it may seem like nothing more than a “Health” app (un-deletable from your phone, naturally) that allows you to enter various health metrics. But Apple’s Health system is way bigger than that. Nike, Fitbit, Withings, Strava, RunKeeper, and iHealth have all announced HealthKit support, so you can expect data generated by those systems to find its way into HealthKit automatically. The iWatch, if such a thing exists, will surely populate data here, too. Apple even announced a partnership with the Mayo Clinic, suggesting a private cloud-based API.

Essentially, HealthKit promises to turn your iPhone (or any iOS device) into a health hub. It’s a recognition from Apple that health data is important in our everyday lives but fragmented and difficult to access with current systems. With HealthKit and iOS 8, instead of opening the Strava app to check your latest ride, the Withings app to check your weight, and the Mayo Clinic website for the results of a recent blood panel, all of that information can be accessed from within Apple’s Health app.

Given that, it’s easy to see how perfectly HealthKit aligns with our mission of keeping all your important numbers in one place. Apple is setting out to solve the same problem we are, only in a smaller domain.

So which types of data does HealthKit support? BMI, blood glucose concentration, heart rate, fiber intake, …. The full list is way too long to show here but Apple lists them in this release note (look at HKTypeIdentifiers.h). As long as the list is, I can imagine it being much larger and I suspect it will steadily grow over time.

We’re happy to announce that we’ve already integrated HealthKit into the Numerous iOS app, making it possible to add your most important health metrics to your personal dashboard. And soon we’ll announce our iOS 8 beta program so you can try it out.

Follow @Scalo on Twitter
Follow @NumerousApp on Twitter

Personal Big Data Goes Mainstream

John and I started Numerous because we believe we’re entering an era of “personal big data”, that is, data from tons of different sources—fitness, health, finance, environment, connected home, connected things, connected everything—and that existing channels don’t fit. So we’re creating a new one: Numerous.

So it was very cool to read an article in Newsweek identifying exactly this trend. According to author Kevin Maney, “We’re entering an age of personal big data, and its impact on our lives will surpass that of the Internet.”

Kevin’s piece matches exactly what we’re seeing with Numerous. Our users are tracking a bewildering variety of data, things we would have never predicted. (One user tracks the number of wind gusts over 30 mph in the last 30 minutes within 5 miles of his house and gets a notification when the number goes over 2, which indicates strong likelihood of fires fueled by the Santa Ana winds. Personal big data indeed.)

We’re hard at work building out a platform so our users can not only follow and share their own numbers but create and share their own types of numbers, or “channels”. (Imagine a Numerous user creating a “Currency Exchange Rate” channel so another user could create and share a USD-to-GBP number just by selecting those two currencies. Soon.)

We agree wholeheartedly with Kevin that we’re at the beginning of something big. And we’re glad that you’re here with us.

Follow @cwood on Twitter
Follow @NumerousApp on Twitter

iOS 8 Preview: iCloud Sign-In

This is the second in a series of blog posts previewing iOS 8-specific features coming to Numerous.

In my last dispatch covering upcoming iOS 8 features I told you about Numerous running in the Today tab of the iOS Notification Center. The response to that article was amazing and resulted in a flood of new users. If you were part of that flood, thanks! This time I’m going to get more geeky and talk about iCloud sign-in, how iOS 8 makes this possible, and why it’s important for Numerous. There’s even a bit of code below, so watch out.

First let’s rewind a bit. As I detailed in an earlier article, Numerous allows users to sign in with Facebook, Twitter, or Google, but we chose not to allow a “traditional” sign-in flow that has the user give an email address and password. We took our share of 1-star dings thanks to that decision but mercifully since adding Google sign-in in v1.1, the number of gripes has gone way down.

Fast forward to WWDC 2014, where Apple announced CloudKit along with this tidbit:

Leverage the full power of iCloud and build apps with the new CloudKit framework. Now you can easily and securely store and efficiently retrieve your app data like structured data in a database or assets right from iCloud. CloudKit also enables your users to anonymously sign in to your apps with their iCloud Apple IDs without sharing their personal information.

Since we’re currently an iOS-only app and nearly every iOS user has an Apple ID, this seemed like the Holy Grail. Let’s dig in a little more to find out exactly how iOS 8 makes this possible.

The above quote is marketing copy from Apple’s website. It sounds exactly like what we want but doesn’t spell out how to get there. Using the fantastic site asciiwwdc.com I looked at the transcript from Session 208 Introducing CloudKit and here’s exactly what Apple’s engineer had to say about it:

How are we going to let you know, your client, your application, what user is logged in? Well, naively you might think let’s give them an email address. We’re not going to do that obviously. That’s private user identifiable information and we don’t want to give that out. So, instead what we do is on a container by container basis come up with a random ID. This is an identifier that is stable so that your application no matter what client it’s running on talking to this container will get the same identifier, but it’s not identifying the user via any personal information. … You can take this identifier and do with it what you will.

A ha! The engineer seems to be saying that each CloudKit storage container has a UUID which is “stable” across devices and app reinstalls for a given iCloud user.

(As an aside, this got me to thinking— the iCloud key-value store has been available since iOS 6. If my app just creates a UUID and sticks it there then don’t I get the same anonymous iCloud sign-in functionality without requiring iOS 8? The answer is yes, it does, but with one huge catch: it‘s not all that hard for the user to delete your app’s key-value store. There’s UI exposed to do this in Settings and Apple tells you how here. Is it likely that a user would delete my app’s iCloud storage? Not at all. But imagine the consequences: the user’s login token is lost to time and all the numbers they’ve created in the app are lost because they can no longer sign in. OK, fun thought experiment but let’s not do that.)

So in iOS 8 if your app is provisioned for CloudKit then you can access your app’s iCloud container simply by calling [CKContainer defaultContainer]. According to the engineer’s statements above, this CKContainer should have a “random ID” associated with it that I can use to identify the iCloud user, right? Nope. No such property exists on CKContainer. It turns out that when the app’s iCloud container is created, a user record is auto-generated and attached to that container, and it’s that user record that we want. With that in mind, here’s the code:

[[CKContainer defaultContainer] fetchUserRecordIDWithCompletionHandler:^(CKRecordID *recordID, NSError *error) {
    ... handle errors ...
    self.magicaliCloudUserID = recordID.recordName;
}];

And just to be double-extra sure, I verified that

• The id is the same for the same iCloud user after an app delete/reinstall
• The id is the same for the same iCloud user after signing out of iCloud and back in
• The id is the same for the same iCloud user on a different device
• The id is different for a different iCloud user on the same device

So that’s it. With just a few lines of code we’ve bagged the Holy Grail: anonymous password-less sign-in using a service that nearly every iOS 8 user is guaranteed to have.

Here’s the final result in all its glory:

Follow @Scalo on Twitter
Follow @NumerousApp on Twitter

Track your Square payments with Numerous and IFTTT

There’s some exciting news for business merchants today: Square and IFTTT announced that sellers can now integrate their Square payments with IFTTT to trigger IFTTT’s custom actions. Made a big sale? Send a w00t email to your whole staff. Issued a refund? SMS the manager so she can follow up with the customer.

Numerous and IFTTT have been a fantastic fit so far and this might be one of the best uses yet so we wasted no time in adding support for IFTTT+Square integrations. Here’s a recipe that updates a Numerous number whenever you make a sale:

And if you’ve never created a number in Numerous that updates via IFTTT, it’s easy. Charlie wrote a great blog post last month with instructions and a video. Check it out.

Follow @Scalo on Twitter
Follow @NumerousApp on Twitter

How Numerous Got Its First 10,000 Users

Yesterday morning Numerous added its 10,000th user—w00t!

It’s only a small step on the path to our first major growth goal of 1 million users, but it’s a good point at which to pause and reflect on how we got here.

It all started with a LaunchRock page and a bunch of emails to people we know, about a hundred of whom signed up to receive updates about our new project.

When we had a beta ready, we emailed our list asking for beta testers. We added those who accepted to TestFlight so they could start using the app. That netted us our first 50 or so users.

Over the course of the beta, we posted to our blog and Twitter which attracted some additional interest. We added another 50 or so users, bringing out total near 100 (which is currently Apple’s limit). After 10 weeks in beta, it was time to release Numerous to the world.

With a zero-dollar marketing budget, we emailed a launch announcement to a handful of reporters and analysts we thought would be interested. This wasn’t a mass email, mind you, these were one-off emails to about a dozen individual people including:

• Stacey Higginbotham (who covers Internet of Things) at GigaOm
• Thorin Klosowski (who writes a lot about IFTTT) at LifeHacker
• Jason Cipriani (who covers mobile and connected devices) at CNET

In each email I was explicit about why I thought they and their readers would be interested.

On launch day we got some great coverage, including a GigaOm piece by Stacey, an article on CNET by Jason, and a story in the Austin Business Journal by Chris Calnan. We also got a mention from indie Mac and iOS developer Brent Simmons that brought in a surge of new users. By the end of the day we had added about 1,500 users, which is way better than zero.

A couple of days later we got another 1,000 from the announcement of our integrations with IFTTT and Zapier, both of which have rabid followings.

Then began the long, slow climb to 7,500 as about 100 new users each day found us on the App Store, heard about us from friends, saw numbers our users tweeted from the app, and otherwise organically came to discover Numerous.

Finally last Thursday John wrote a blog post showing our upcoming integration with the iOS 8 Today view. The next day the news got picked up by Zac Hall at 9to5Mac and by Monday morning we had added another 2,500 users pushing us past the 10,000 mark.

It’s now Tuesday afternoon and the number of Numerous users stands at 11,274—a 50% increase in the last 4 days. (Thanks, Zac!)

So how did we get our first 10,000 users? There was certainly no magic bullet; we just hammered away. Which is exactly how we plan to get our next 990,000—and beyond.

If you haven’t tried Numerous yet, please do! It’s on te App Store at http://appsto.re/us/ycXIV.

Follow @cwood on Twitter
Follow @NumerousApp on Twitter

iOS 8 Preview: Numerous in Today

This is the first in a series of blog posts previewing iOS 8-specific features coming to Numerous.

Last month at WWDC 2014 Apple astonished the developer community with a torrent of announcements and features including iOS 8, OS X Yosemite, and a new programming language called Swift.

As I watched the keynote on Apple TV I actually found it difficult to keep up with all the new technologies and features being revealed, but one iOS 8 feature in particular immediately struck me as something that we absolutely must do for Numerous.

In case you’re not familiar, iOS 7 introduced a redesign of the iOS Notification Center that includes not only the notifications you’ve received but a new view called Today that shows you lots of stuff that’s important right now — meetings, stocks, traffic, and more — and this view is always available by dragging down from the top of the screen, even when the device is locked.

Fun fact: probably my biggest contribution to iOS 7 from when I worked at Apple is the Stocks part of that view!

So what changed in iOS 8? Apple is opening up this view to developers so any app on your iPhone or iPad can provide content to display there. Of course, the user has the option of organizing the content any way they like or to turn it off completely.

Our primary mission at Numerous is to make the most important numbers in your life easily accessible. Clearly, making them available to users without having to launch the app or even unlock their phones will be great.

While iOS 8 isn’t slated to ship until “This Fall” (and that likely means very early Fall), we’re happy to say that we already have Numerous in the Notification Center’s Today tab working. From within the app you can select as many numbers as you’d like to appear in Today and even order them differently than they are in the app. It looks like this:

We hope you’re as excited about iOS 8 as we are. Check back here in the coming weeks to learn more about how we’ll be adopting other upcoming great technologies.

Follow @Scalo on Twitter
Follow @NumerousApp on Twitter

Creating Auto-Updating Numbers with IFTTT

At Numerous, one of our favorite third-party services is IFTTT (short for "If This Then That", rhymes with "gift"). Many of our users use IFTTT to create numbers in Numerous that update automatically. Here's a quick video showing how it's done:

Personally, I use IFTTT to connect my Withings scale and my Automatic Link to Numerous to track my weight and the miles I drive every day:

(Note that I combine two IFTTT recipes for my mileage: one to increment mileage after every trip and one to reset that number to zero every night.)

IFTTT currently supports over 100 apps and devices, so we've only just scratched the surface with what it can do with Numerous. We'd love to hear about the recipes you create so if you do so, please leave a comment here.

Thoughts on Sign-In

The current average rating of Numerous on the Apple App Store is 4 stars, with 5-star reviews outnumbering all others by more than two to one:

We’re pretty proud of that so it stings a little when we see a 1-star review. There aren’t many, but there are a few, and virtually all of them look something like this:

Khåymaan (thanks for the review, Khåymaan!) is alluding to the fact that the Numerous app requires signing in with Twitter or Facebook (as of v1.1 we also allow signing in with via Google). We don’t allow users to supply an email address and a password to create their account and we never post to the user’s social network without their permission.

So given that a vocal minority of people detest being forced to sign in with a social networking account, that they bring our ratings down with 1-star reviews, and that we’ve probably lost out on a significant number of users, why shouldn’t we just add an email login? Give the people what they want, right?

At every turn we’ve thought about this and at every turn we’ve concluded that taking email addresses and passwords is the wrong way to go. Here’s why.

Risks

It seems that every week I hear another story about a major company leaking thousands of email addresses, credit card #s, and password hashes. This week it was Domino’s Pizza but in many cases these are major technology companies who I’d think would have a handle on protecting their customers’ data. But hackers are smart and even the best security engineers make mistakes. I’m confident that we could safely store email addresses and passwords (randomly salted and hashed, of course!) if we chose to, but doing so always comes with some amount of risk that we prefer to avoid.

“Social Login” Provides Control

This is often overlooked, but by logging in with a service such as Facebook, Twitter, or Google, you’ve retained complete control over what the app can do. Is the app harassing your friends or spamming your timeline? Bad app!! A visit to Facebook’s or Twitter’s application access dashboards allows you to dial back what the app can do or completely revoke its access to your account. On the other hand, if you give away your personal email address then the cat’s out of the bag. There’s no stopping a malicious developer from selling your email to hoards of Viagra spammers.

User Experience

Typing an email address and a password on a phone is unpleasant. Tapping a button is easy. We want to make the sign-up process as quick and simple as possible.

Forgotten Passwords

According to Microsoft’s “A Large-Scale Study of Web Password Habits”, about 4% of users will forget their passwords every three months. To accommodate forgotten passwords, we would need to implement temporary password creation & storage, password email exchange, and password change enforcement. That’s a huge chunk of work and each of those moving parts is another potential vector for attack by hackers.

Time & Resources

On a recent episode of the excellent Debug podcast, John Gruber shared that adding email/password sign-in to their app Vesper “put us back a month or maybe more.” The fact that it took an experienced three-person team a month to get the pieces in place is a testament to the immense complexity of doing email/password sign-in. In the same time period we could probably add 2 or 3 major features. Or, you know, ship.

A friend once pointed out the sad irony in the fact that the major providers of OAuth sign-in, Facebook and Twitter, also happen to be social networking companies. This is so true. If only there were a company capable of authenticating millions of user accounts that didn’t also run a social network. Oh wait…

CloudKit

At WWDC 2014, Apple announced CloudKit:

Leverage the full power of iCloud and build apps with the new CloudKit framework. Now you can easily and securely store and efficiently retrieve your app data like structured data in a database or assets right from iCloud. CloudKit also enables your users to anonymously sign in to your apps with their iCloud Apple IDs without sharing their personal information.

For us, that’s pretty much the Holy Grail. An account type that every user of our app is guaranteed to have, but doesn’t link to a social network, and is explicitly guaranteed to be anonymous. We fully expect to have iCloud anonymous sign-in in Numerous as soon as it’s available in iOS 8.

In the mean time, we’ve just added Google sign-in to Numerous v1.1 so anyone with a Gmail address can create a Numerous account. We think this is a great alternative for those not wanting to use Facebook or Twitter.

Follow @scalo

New native IFTTT and Zapier support, Google signin

We just released Numerous v1.1, which contains some big new features we think you're going to like.

Native IFTTT and Zapier Support

Since day one you've been able to use IFTTT and Zapier to connect Numerous to hundreds of the most popular devices and applications—but the process was a little complicated. So we've added native support for those services to streamline the process.

You can now create numbers that are automatically updated by IFTTT or Zapier, right from within Numerous.

Sign in with Google

We heard from a number of people that they didn't want to sign in with Twitter or Facebook, so you can now sign in securely with your Google account.

New users can create a Numerous account simply by signing in with Google.

If you already have a Numerous account you can link it to your Google account, which will enable you to sign in with Google in the future. Just sign in with the service that's already associated with your Numerous account, then from the menu choose “Edit Profile > Link Google Account”.

We do not store email addresses or passwords and will never post to your social networks without your permission.

The Little Things

In addition to the big headline features, this update includes a bunch of smaller enhancements, including:

• Web links in comments
• More hints to help you get started
• Custom transition animations
• “Event” numbers now include the original date in the description
• Inline error display (handy for API debugging)
• Numerous bug fixes
• Loads of updates to the REST API

Numerous v1.1 is now available on the App Store, so go get it and let us know what you think. As always, please let us know if you have any questions or run into any problems. Thanks!