Consuming JSON APIs with Go

We live in a time where there is an API for almost anything.

Part 1

These study notes is an attempt to write about “Consuming various JSON APIs with Go” as I explore and experiment, in the hope that a new Go developer can understand and get up-to-speed with them in no time.

ProgrammableWeb is the world’s largest API repository (also do look at Mashape) and the first API I am going to take a look at is NumVerify.

NumVerify offers a full-featured yet simple RESTful JSON API for national and international phone number validation and information lookup for a total of 232 countries around the world.

After signing up (free plan), every user is assigned a personal API Access Key — a unique “password” used to make requests to the API.

To authenticate with the numverify API, simply attach your access_key to the base endpoint URL:

In addition to the “access_key” parameter, there is only one required parameter (“number”) to start validating phone numbers.

Type the following in your browser window:

The API response is returned in JSON format.


JSON-to-Go is an excellent tool that instantly converts JSON into a Go type definition. Using it, I get:

Our Go program “numverify.go” is a bare bones program showing you how to access the “numverify” API. Later on you could convert this to a web app and host it on Google App Engine or Heroku.

Here’s the complete program:

func QueryEscape(s string) string

“QueryEscape” escapes the string so it can be safely placed inside a URL query.


“Sprintf” formats and returns a string without printing it anywhere.

func NewRequest(method, urlStr string, body io.Reader) (*Request, error)

“NewRequest” returns a new “Request” given a method, URL, and an optional body. “NewRequest” returns a “Request” suitable for use with “Client.Do”.

client := &http.Client{}

A “Client” is an HTTP client.

resp, err := client.Do(req)

“Do” sends an HTTP request and returns an HTTP response. When “err” is nil, “resp” always contains a non-nil “resp.Body”. Callers should close “resp.Body” when done reading from it. Use “Defer” for closing the body. “resp.Body” is of type “io.Reader”.

defer resp.Body.Close()

Next, “NewDecoder” returns a new decoder that reads from “io.Reader”. A “Decoder” reads and decodes JSON objects from an input stream.

func NewDecoder(r io.Reader) *Decoder

“Decode” reads the next JSON-encoded value from its input and stores it in the value pointed to by v.

func (dec *Decoder) Decode(v interface{}) error

Finally, we extract the information from our populated “Numverify” struct variable “record”.

Note: I would love your feedback on these study notes. If I can make it better, I’d love it!

(These notes were updated on 29th Oct. 2016).

In Part 2, I talk about using currencylayer API that provides a simple REST API with real-time and historical exchange rates for 168 world currencies, delivering currency pairs in universally usable JSON format.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store