ipify

README

ipify

An unofficial client library for ipify: A Simple IP Address API. Based on the official library.

Purpose

ipify is the best IP address lookup service on the internet. It's fast, simple, scalable, and open source.

In short: if you need a way to pragmatically get your public IP address, ipify is the best possible choice!

This library will retrieve your public IP address from ipify's API service, and return it as a string. It can't get any simpler than that. Usage documentation is below.

This library also has some other nice features you might care about:

• If a request fails for any reason, it is re-attempted 3 times using an exponential backoff algorithm for maximum effectiveness.
• This library handles errors properly, and usage examples below show you how to deal with errors in a foolproof way.
• This library only makes API requests over HTTPS.

Installation

To install ipify, simply run:

$ go get github.com/tech10/ipify

This will install the latest version of the library automatically.

Usage

Using this library is very simple. Here's a simple example:

package main

import (
	"fmt"
	"github.com/tech10/ipify"
)

func main() {

	// Initialize variables.
	// We will be resolving to IPV4, IPV6, or which ever comes first.
	// This will fully demonstrate the use of the library.

	var ip string
	var ip4 string
	var ip6 string
	var err error

	// This will resolve to IPV4 or IPV6, which ever comes first.
	ip, err = ipify.GetIp()
	if err != nil {
		fmt.Println("Couldn't get my IP address:", err)
	} else {
		fmt.Println("My IP address is:", ip)
	}

	// For IPV4 only.
	ip4, err = ipify.GetIp4()
	if err != nil {
		fmt.Println("Couldn't get my IPV4 address:", err)
	} else {
		fmt.Println("My IPV4 address is:", ip4)
	}

	// For IPV6 only.
	ip6, err = ipify.GetIp6()
	if err != nil {
		fmt.Println("Couldn't get my IP address:", err)
	} else {
		fmt.Println("My IPV6 address is:", ip6)
	}
}

In regards to error handling, there are several ways this can fail:

• The ipify service is down (not likely), or:
• Your machine is unable to get the request to ipify because of a network error of some sort (DNS, no internet, etc.).
• If attempting to get IPV6 or IPV4 addresses only, your machine is unable to either resolve or connect to the API. For instance, if your network connection doesn't support IPV6, you will be unable to use the GetIp6 function.

The library will output an informative error message in the event anything fails.

One thing to keep in mind: regardless of how you decide to handle errors, the ipify library will retry any failed requests 3 times before failing, so if you do need to handle errors, remember that retry logic has already been attempted.

Contributing

If you'd like to improve this library, please send me a pull request. I'll be happy to review them, and if they seem like a good idea, merge them.

The standard contribution workflow should look something like this:

• Fork this project on Github.
• Make some changes in a feature branch.
• Send a pull request when ready.

Also, if you're making changes, please write tests for your changes. This project has a full test suite you can easily modify / test.

To run the test suite, you can use the go test command after forking this repository.

Documentation

Overview

Package ipify provides multiple methods for retrieving your computer's public IP address from the ipify service: http://www.ipify.org While it uses ipify by default, you are free to use any service you like.

Index

• Constants
• Variables
• func GetIp() (string, error)
• func GetIp4() (string, error)
• func GetIp6() (string, error)
• type Ip
  • func DefaultIp() *Ip
  • func (i *Ip) Retrieve() error

Constants

const API_URI_4 = "https://api.ipify.org"

This is the ipify service base URI for IPV4 resolution.

const API_URI_6 = "https://api6.ipify.org"

This is the ipify service base URI for IPV6 resolution.

const API_URI_64 = "https://api64.ipify.org"

This is the ipify service base URI for IPV4 or IPV6 resolution, whichever comes first.

const MAX_TRIES = 3

The maximum amount of tries to attempt when making API calls.

const VERSION = "1.0.0"

The version of this library.

Variables

var USER_AGENT = fmt.Sprintf("ipify/%s go/%s %s", VERSION, runtime.Version()[2:], strings.Title(runtime.GOOS))

The user-agent string is provided so that I can (eventually) keep track of what libraries to support over time. EG: Maybe the service is used primarily by Windows developers, and I should invest more time in improving those integrations.

Functions

func GetIp

func GetIp() (string, error)

GetIp queries the ipify service (http://www.ipify.org) to retrieve this machine's public IP address. Returns your public IP address as a string, and any error encountered. By default, this function will run using exponential backoff -- if this function fails for any reason, the request will be retried up to 3 times.

This function will return either the IPV4 or IPV6 address, which ever resolves first.

Usage:

package main

import (
	"fmt"
	"github.com/tech10/ipify"
)

func main() {
	ip, err := ipify.GetIp()
	if err != nil {
		fmt.Println("Couldn't get my IP address:", err)
	} else {
		fmt.Println("My IP address is:", ip)
	}
}

func GetIp4

func GetIp4() (string, error)

GetIp4 returns the IPV4 address of your computer. Use this as you would use the GetIp() function.

func GetIp6

func GetIp6() (string, error)

GetIp6 returns the IPV6 address of your computer. Use this as you would use the GetIp() function.

Types

type Ip

type Ip struct {
	Ip4f func() (string, error) // Function to retrieve IPV4 address.
	Ip6f func() (string, error) // Function to retrieve IPV6 address.
	Ip4u string                 // URL to use to retrieve IPV4 address.
	Ip6u string                 // URL to use to retrieve IPV6 address.
	Ip4  string                 // IPV4 address once retrieved.
	Ip6  string                 // IPV6 address once retrieved.
	Ip4e error                  // Error value if unable to retrieve IPV4 address.
	Ip6e error                  // Error value if unable to retrieve IPV6 address.
}

A struct to retrieve your IP address in any way you would like. You can define your own functions to call that can be used to retrieve your IP address.

func DefaultIp

func DefaultIp() *Ip

Initialize a default Ip struct with appropriate functions and the URL's necessary to retrieve your IP addresses, IPV4 and IPV6.

func (*Ip) Retrieve

func (i *Ip) Retrieve() error

Retrieve IPV4 and IPV6 addresses, or only one of them, depending on which function is nil.