The following post was written by our newest team member @deland, and it is something between an introduction to the Hyperpublic API and a documentation of a first experience with it. The actual use case described below is just a toy application - but it provided an opportunity for some cool visualizations. We hope you enjoy it and come up with some cool uses of your own!

If you haven't already, the first thing you're going to need to do to get started with the API and follow along (or experiment on your own) is to register for a Hyperpublic API key. It's free! It's fun! There are API wrappers for many programming languages so you can choose your favorite and get started right away. I'm going to be describing my method using Python, but the syntax in all the languages is pretty straightforward.

We're going to focus on pizzerias in New York City because everyone loves pizza (and because we had to choose something). The Hyperpublic API is a window into the world indexed by (exact) location. We can query the API by sending it addresses, zip codes, phone numbers, or latitudes and longitudes as well as categorical information (more on this in a moment). The query we send the API is then resolved to a specific latitude and longitude, and nearby places satisfying the query are returned. This means if we send the API a generic location like "New York, NY", a specific latitude and longitude is set, and then the search is executed. What this really means is you may not get what you wanted if you use such a generic location! The parameters available to query the API are described here, as is the structure of the documents that will be returned to you.

The categorical information in included in the query quite easily. We ask for places with a specific category (restaurant, office, etc) or we can ask for the database to be searched for other text (via the parameter 'q', for query). All locations with a place-name or tag matching your text will be returned. So we will query the API using the location parameter and also q = 'pizza'. For reasons that will become clear soon, I took the result of the queries and stored them in a local Mongo database . To be able to get all pizzarias in new york city, I looped over all the zipcodes in new york. The API only returns 50 locations at a time, but we can ask for more. Here is the relevant code:

from hyperpublic import *
...
for zip in zipcodes:
   inserted = 0
   notinserted = 0
   for p in range(1,rounds + 1):
      try:
         items = hp.places.find(location=str(zip),q="pizza", page = p, page_size = 50)
      except:
         break
      for item in items:
         try:
            dbh.nypizza.insert(item, safe = True)
            inserted += 1;
         except DuplicateKeyError:
            notinserted += 1
    print "%d items inserted and %d duplicates found for zipcode %d" % (inserted, notinserted, zip)


Here, my local mongodb connection is called dbh and the collection is called nypizza. Because some zip codes don't cover that much area - many of these queries will return the same pizzerias as other queries. This may not be a problem depending on your application, but you also might want to be aware of it (I just prevented mongo from duplicating records by inserting a key on the id field). Now we have the location of all (I get 2439) pizza places in the city - how easy was that?!

Probably we want to visualize all the locations at once. There are many options for doing this - and many existing python libraries to make our lives easier. For visualization only, my favorite tool (so far) was created by Seth Golub. It creates a heatmap based on density of points, and can overlay the 'heat' on top of maps coming from OpenStreetMap . This image is available under CC-BY-SA.

Depending on your needs, you can also overlay this information onto Google Earth maps or Gmaps. The nicest tool I found for this is hosted here. The interface is incredibly easy. Here is the output (it spits out kml data which google earth can read, and can also be accessed by google maps):

You might start wondering, "if I wanted to go on a 'pizza-slice' tour of new york city, and I wanted the longest sequence of pizzerias separated by .1 miles without visiting any place twice - what would I do?". Coincidentally, I wondered the exact same thing, and wrote a short function to search the graph for the longest such path. (For those who care, finding the longest path in a graph with cycles is known to be NP-hard. So don't try this on your big graphs.) Here is the result, you can visit 32 pizzerias (labeled, in order,it A-Z, then 0-5). Best of luck.

Permalink | Leave a comment  »

We're looking for an outgoing, technically minded person to represent Hyperpublic in the developer community. You love technology and people. You’ll craft and execute an outreach strategy to get the word out about our platform with developers and companies. Dream up any creative idea and make it happen. You’ll get to work with some of the smartest hackers, designers, and entrepreneurs in the technology startup community.

Permalink | Leave a comment  »

This weekend General Assembly is hosting the Reinvent Local Hack Day. Hyperpublic, and companies like American Express Open Forum, Yipit, NYC.gov, ordr.in, and more will be presenting tools and services that they've built aimed at helping local businesses connect with their communities. 

If you have any good ideas for applications that you'd like to see built that help you interact with the local businesses around you then swing on by General Assembly, or tweet using the #reinventlocal hashtag, and maybe your idea will come to life this weekend.

Permalink | Leave a comment  »

Want to find a place by phone number? Now it’s easy using the Hyperpublic platform. As a developer, you can easily search our Places+ product by phone number.

We built this based on developer requests so please let us know what to build next. Who should you call? Well, whichever company is at 212 229 2217 of course:

You can also query using formatted phone numbers (i.e. with a leading +1, trailing extension, various non-digit characters, etc...) using the same phone_number parameter. Here's the same query using +1 (212) 229 - 2217:

Permalink | Leave a comment  »

On Thursday, November 3rd, Hyperpublic's head of engineering, Doug Petkanics, will be teaching a Skillshare class called "APIs For Beginners." The class will start with the basics, and will cover the following:

Permalink | Leave a comment  »

Do you love pure functional programming, strong typing, *and* Hyperpublic's API? Well you're in luck: there is now an official API library for the Haskell language. Check it out on GitHub (https://github.com/mkscrg/hyperpublic-haskell) or Hackage (http://hackage.haskell.org/package/hyperpublic). The docs on Hackage and the source distribution include some example code, and usage questions can be posted to this list.

Let us know what you think!

Permalink | Leave a comment  »

AdRunner (Winner of 2nd Place Prize)

Permalink | Leave a comment  »

Hyperpublic is proud to be presenting today at the Fall 2011 HackNY Hackathon. HackNY is a non-profit organization in NYC who's aim is to "federate the next generation of hackers for the New York innovation community". Twice per academic year, once in the fall and once in the spring, they bring together undergrad and graduate computer science students from all over the Northeast for a 24-hour hackathon hosted at NYU. 

Permalink | Leave a comment  »

Two of Hyperpublic's engineers, @ericxtang and @zanecstarr, as well as a couple of our investors and advisors are alums of Carnegie Mellon's computer science program, so we're eager to support CMU students when they're interested in learning about the NYC startup scene. This weekend, about 6 CMU undergrads were looking to make the trip from Pittsburgh to New York in order to participate in a weekend hack event with other local college students. We were going to sponsor their bus tickets, but Eric thought it'd be more fun to get out to Pittsburgh and road trip with the gang. Details of their journey to follow today...

6:30am - Rise and Shine

7:30am - Goodbye New York (for a few hours)

9:55am - Hello Pittsburgh

See the full gallery on Posterous

11:55am - Arrival at CMU

2:55pm - Nap time in the van back to NYC

See the full gallery on Posterous

6:20pm - NYC Pulls into view

 

8:20pm - Donatello's Pizza after a long trip. Totally hits the spot!

 

11:30pm - After a long day of traveling, eating and hanging out, the team retires to the AirBnb apartment in downtown Manhattan.  Rest up for a weekend of hacking!

Permalink | Leave a comment  »

This FAQ answers many of the commonly asked questions about our Geo Deals and Events product. If you have a question that isn't answered here, feel free to email us at affiliates@hyperpublic.com.

Permalink | Leave a comment  »

The last few months have been busy at Hyperpublic and we’d love to tell you about two great local data APIs: Places+ and Geo Deals and Events.

Places+ returns nearby businesses and other points of interest (POI). Our places data set has freshest and most accurate information from the web. You can query the API from many popular languages and use it in your web and mobile applications.

Geo Deals and Events is a collection of real time local offers including daily deals, meet ups, exhibitions and other types of events that can be integrated into any app or web service. When your users interact with these offers, you get paid through our local offers monetization plan.

For this post, we'll focus on calling the API through simple URLs that you can try in your browser. We’ll walk through what the requests and results look like and how they're constructed.

The Places+ API returns points of interest around a specific location. Here are places around Hyperpublic HQ:

Click and you'll get a block of raw JSON. 

That's an array of JSON objects: each one represents a place in the Places+ database. Each place includes useful information like its name, lists of tags and properties, and its locations with street address and latitude/longitude.

In most cases, API calls are simply GET requests to (carefully constructed) URLs. Let’s review each piece of the example above:

• https://api.hyperpublic.com/api/v1 — This is the base URL for Hyperpublic API requests. Hyperpublic requires SSL for all requests.
• /places — Include this path after the base URL to access the Places+ endpoint. Other endpoints use different paths.
• ?...&...&... — These are query parameters. Following the ? is an &-separated list of key=value pairs. You use these to define your search and pass your authorization credentials:
  • address=416%20W%2013th%20St%2C%20NY%2C%20NY%2C%2010014 — The address parameter takes a URL-encoded address. For this example, we URL encoded "416 W 13th St., New York, NY, 10014".
  • client_id=..., client_secret=... — These are the Client ID and Client Secret values you're given when you register an application. They must be included in every API call. (The values used in this post are just for documentation and examples. Don't use them in your own applications!)

By default, all location queries return at most 10 results inside a 2 km radius. You can override the defaults by passing the relevant query parameters. To get more results, include limit=50, or to search within a 0.5 km radius, include radius=0.5. How about the closest Japanese restaurant to Madison Square Garden? Combine category=japanese with the lat, lon, and limit parameters, and you're there:

You can get a specific place by making requests to /places/ID, where ID is the value of the id field in that place’s JSON representation. Here's how to get that same sushi restaurant without searching:

Calling the Geo Deals and Events endpoint is as easy as substituting /offers for /places in the request URL. The basic search and show functionalities are the same as with Places+, but some of the query parameters are different. Let's find offers near Prospect Park, Brooklyn, that cost less than $50:

And we can request a specific offer the same way we requested a specific place:

This is a basic introduction to the Hyperpublic API; check out the API documentation for a full reference. The documentation pages will be updated with new features as we roll them out, so check back often! Our Geo Code blog will have more posts to show how to use language-specific libraries to easily integrate Hyperpublic into your applications.

Got questions? Post to our API Developers Google Group and we'll be glad to help you out. Happy hacking!

Permalink | Leave a comment  »

Permalink | Leave a comment  »

We've spent a lot of time over the past year talking with developers about what they are looking for in terms of local data. Everybody has different requests depending upon what they're building, however certain requests come up time and time again.

Permalink | Leave a comment  »

Monads are one the most talked about "features" of the Haskell language. The web abounds with monad tutorials and monad examples, yet they maintain a reputation for giving newcomers a hard time. What are monads, and what are they good for? Do you even have to code in Haskell to use them? We'll approach monads from a problem-oriented perspective, with discussions of some other important type classes along the way.

Permalink | Leave a comment  »

Permalink | Leave a comment  »

The engineering team at Hyperpublic has been hard at work over the last few weeks re-architecting our platform in order to migrate from a relational database (PostgreSQL) to a NoSQL datastore (MongoDB). We completed the migration about two weeks ago, and nothing major has broken down so far, so it's about time to do a recap so that the community can benefit from what we learned along the way. This post starts off anecdotal and moves to technical, and hopefully after reading it you'll have a good background on the reasons why you may want/need to migrate and how to go about performing the migration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

module MongoHP
  class HPObject
    include Mongoid::Document
    include Mongoid::Timestamps
    store_in :hp_objects
    
    field :object_type, :type => String
    field :tags, :type => Array
    ...

    # Embeds
    embeds_many :images, :as => :photo_owner, :class_name => "MongoHP::Image"
    embeds_many :locations, :class_name => "MongoHP::Location"
    
    ...
  end
 
  class Location
    include Mongoid::Document
    include Mongoid::Timestamps
    embedded_in :hp_object, :class_name => "MongoHP::HPObject"
  end

  class Image
    ...
  end
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

  class CopyPlaceJob
    @queue = :general

    def self.perform(id)
      old_place = ::Place.find(id)
      mongo_user = MongoHP::User.first(:conditions => {:old_id => old_place.user_id})
      if mongo_user
        place = mongo_user.hp_objects.create(:old_id => old_place.id,
                                             :object_type => "Place",
                                             :display_name => old_place.name,
                                             :description => old_place.description,
                                             :phone_number => old_place.phone_number,
                                             :website => old_place.website,
                                             ...)
        MigrateToMongo.migrate_object_tags(place, old_place)
        MigrateToMongo.migrate_object_images(place, old_place)
        MigrateToMongo.migrate_object_locations(place, old_place)
      end
    end
  end

Permalink | Leave a comment  »

What's up people? This weekend, May 21-22, the Hyperpublic engineering team will be hanging out at the Techcrunch Disrupt Hackathon in New York City at Pier 94. We'll present our developer platform on Saturday afternoon to anyone who's interested in learning how to build an application which leverages rich local data.

View Larger Map

Permalink | Leave a comment  »