Posted on 04-04-2012
A big part of API evangelism, is storytelling. Storytelling about the API, the value it delivers, and the solutions it provides. Through my own hacking on an API, engaging with developers via email, a forum and social media, I gather ideas for projects that would help evangelize an API, while also educating users of how it works.
One example is a recurring question I get from CityGrid API developers--how does CityGrid compare with other places APIs like Google Places and Yelp?
I set out to answer this question, quickly realizing it was easier said than done. I found 11 places APIs that fit my criteria, and they had many differences, so I started by writing a quick overview of the 11 places APIs. This helped me identify and quickly understand what each places API delivered.
Then I realized that I needed to actually hack on each API to truly understand how they work, and develop enough of an understanding where I could compare them in detail. To do this, I needed a project, to use as a anchor for my storytelling. Not just one blog post, but many, with code samples and starter kits to help support the project.
I chose to build an Interactive Places API Comparison Tool.
As a start, I chose 3 places APIs to compare: CityGrid, Google and Yelp. The Interactive Places API Comparison Tool provides a what and where textual search as well as a latitude and longitude search, simultaneously across the 3 APIs.
Once I built the first prototype I blogged about the comparison tool for the first time, as well as some of the research that went into it, like Places API request format comparison--talking about how CityGrid, Google and Yelp each tailored their API requests.
Today I finished a report to support the what and where search and one for the latitude and longitude search. The report shows what was searched for, how many listings were pulled from each API and number of images, offers, reviews and tips for each place returned. I will be adding other reporting items in the future.
So far I’ve produced a lot of quality content from this hacker storytelling project:
- 5 Blog Posts
- Interactive API Comparison Web Application
- Code Samples for Searching and Pulling Places Detail for 3 APIs
- Code Libraries for Each of the 3 APIs
All blog posts are syndicated out to Twitter, LinkedIn and Facebook as well as bookmarked at Reddit, StumbleUpon and Hacker News. All code samples live as Github Gists so I can embed in blog posts and other places, while code libraries live as Github repositories.
I’m about to post a bew blog post about the Interactive Places API Comparison reports I just finished, and will be adding Factual and Foursquare to the list of APIs that are compared as part of the tool. This will give me probably four or five more blog stories in the next couple days.
It is hard to tell where the project will go after that. The good hacker storytelling projects just keep living and producing blog posts, code samples, code libraries and starter kits. But there will always be new ideas for projects and stories when I engage with developers within the API community and on the open Internet.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- My API 101 Workshop At @APIStrat In Chicago Next Week
- Some Advice For The Enterprise When Beginning Your API Journey
- Machine Readable API Definition Format Swagger Matures to 2.0
- How Do We Continue Moving Green Button Data And APIs Forward?
- Beyond Public APIs In Government: Internal Access to Resources
- Can You Show Me The ROI On All Of This API Stuff Before We Commit
- In The Future APIs Will Be Default For All Cities
- No Public APIs Are Not Going Away Just Cause A Few BigCos Fumble At It
- Internal API Search Engine For Everyone At Your Company (Not Just Developers)
- If You Need Assistance With Your Healthcare API Strategy I Have The Person
- Explaining APIs To Senior Leadership: Access To Company Resources Without The IT Hassle
- A Conversation With @ijroth, @dorkitude, @antonyfalco, and @medjawii In The Next Generation API Stack Panel @APIStrat
- API Evangelist Thoughts On The Right To An API Key And Algorithmic Organizing
- Explaining APIs To Your Senior Leadership
- An API Evangelism Strategy To Map The Global Family Tree
- Thank You For Your API Evangelist Blog(s)
- Video From The Hypermedia Panel At API-Craft In Detroit Last Month
- Please Open Source Your API Before Shutting It Down
- Explaining My Work Around APIs In Higher Education To Institutions
- You Can Have An API Just By Choosing Products And Services That Have APIs
- Using Excel As An API Datasource And An API Client For The Masses
- Brewing Up Something Awesome With The Jive Software API
- Relationship Between APIs And Containers
- Real-time and Visualizations Will Be Key in Financial API Deployments
- Notification Focused Startups Within Leading API Ecosystems