Geo Code

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

(download)

Click here to download:

hyperpublic-brings-cmu-to-new-york-pcanABxfCtqhlbIHGnnI.zip (231 KB)

11:55am - Arrival at CMU

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

(download)

Click here to download:

hyperpublic-brings-cmu-to-new-york-cFpDjGIDhfsBJeAoAfmh.zip (169 KB)

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!

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.

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!

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.