ColdFusion Gateway For IPInfo.io Geolocation Service

<cfscript>

	ipInfoGateway = new IPInfoGateway();

	// Get the entire geolocation data structure.
	info = ipInfoGateway.getInfo( "69.4.2.100" );

	// Pull back just the given field (uses a different API resource).
	field = ipInfoGateway.getField( "69.4.2.100", "city" );

	// Output results.
	writeDump( info );
	writeOutput( "<br />" );
	writeDump( "City: #field#" );

</cfscript>

component
	output = false
	hint = "I provide client access to the IPInfo.io API."
	{

	/**
	* I initialize the IP Info gateway with the optional API key. If provided, the API
	* key will be used to make all geolocation calls to the remote API.
	*
	* @apiKey I am the authorization token for paid IPInfo.io subscription plans.
	* @output false
	*/
	public any function init( string apiKey = "" ) {

		setApiKey( apiKey );
		setHttpTimeout( 5 ); // Default timeout in seconds.

		return( this );

	}


	// ---
	// PUBLIC METHODS.
	// ---


	/**
	* I return the sub-field of the geolocation information for the given IP address.
	*
	* NOTE: If the given field is not defined for the given IP address (assuming the
	* IP address can be geolocated), an empty string will be returned.
	*
	* @ipAddress I am the address being geolocated.
	* @field I am the sub-field being extracted.
	* @output false
	*/
	public string function getField(
		required string ipAddress,
		required string field
		) {

		var content = executeRequest( ipAddress, field );

		// If the given field is not defined for the given IP address, just return the
		// empty string (rather than throwing an error).
		if ( content == "undefined" ) {

			return( "" );

		}

		return( content );

	}


	/**
	* I return the full geolocation information for the given IP address.
	*
	* @ipAddress I am the address being geolocated.
	* @output false
	*/
	public struct function getInfo( required string ipAddress ) {

		var content = executeRequest( ipAddress, "" );

		// CAUTION: At this point, we're assuming that if the request was executed
		// successfully (ie, returned with a 2xx status code), the content contains
		// valid JSON data - that is part of the API contract.
		return( normalizeStructuredData( deserializeJson( content ) ) );

	}


	/**
	* I set the API key used to make requests to the remove API service.
	*
	* From the documentation:
	* --
	* Free usage of our API is limited to 1,000 API requests per day. If you exceed
	* 1,000 requests in a 24 hour period we'll return a 429 HTTP status code to you.
	* If you need to make more requests or custom data, see our paid plans, which all
	* have soft limits.
	* --
	*
	* @newApiKey I am the token used to define a paid subscription.
	* @output false
	*/
	public void function setApiKey( required string newApiKey ) {

		apiKey = newApiKey;

	}


	/**
	* I set the HTTP timeout (in seconds) to be used when calling the remote API service.
	*
	* CAUTION: This won't necessarily cut the request off if the given timeout is
	* exceeded. Ultimately, releasing the request is the purview of the underlying Java
	* layer, which may exceed the HTTP timeout because reasons.
	*
	* @newHttpTimeout I am the HTTP timeout in seconds.
	* @output false
	*/
	public void function setHttpTimeout( required numeric newHttpTimeout ) {

		httpTimeout = newHttpTimeout;

	}


	// ---
	// PRIVATE METHODS.
	// ---


	/**
	* I call the remote IPInfo.io API and return the response string. If the request
	* cannot be fulfilled, an error is thrown.
	*
	* NOTE: The content of the request is not validated - only the HTTP status code.
	*
	* @ipAddress I am the address being geolocated.
	* @field I am the sub-field of the geolocation data being extracted.
	* @output false
	*/
	private string function executeRequest(
		required string ipAddress,
		required string field
		) {

		// Use the field value to determine which end-point to call.
		var resource = len( field )
			? "https://ipinfo.io/#ipAddress#/#field#" // Will always return a single string.
			: "https://ipinfo.io/#ipAddress#/json" // Will always return JSON.
		;

		var apiRequest = new Http(
			method = "get",
			url = resource,
			getAsBinary = "yes",
			timeout = httpTimeout,
			throwOnError = false // Do NOT throw errors for non-2xx status codes.
		);

		// Add the paid-subscription API key if it exists.
		if ( len( apiKey ) ) {

			apiRequest.addParam(
				type = "url",
				name = "token",
				value = apiKey
			);

		}

		var apiResponse = apiRequest.send().getPrefix();

		// Even though we are asking the request to return a Binary value, the type is
		// only guaranteed if the request comes back properly. If something goes terribly
		// wrong (such as a "Connection Failure"), the fileContent will still be returned
		// as a simple string (feels buggy, but what can you do?).
		var content = isBinary( apiResponse.fileContent )
			? charsetEncode( apiResponse.fileContent, "utf8" )
			: apiResponse.fileContent
		;

		// Check for non-2xx status codes.
		if ( ! reFind( "2\d\d", apiResponse.statusCode ) ) {

			// If the error is due to rate-limiting, let's break that out as a different
			// error type. This information may be valuable to the calling context that
			// may be able to manage rate-limiting.
			var errorType = find( "429", apiResponse.statusCode )
				? "IPInfo.TooManyRequests"
				: "IPInfo.HttpError"
			;

			throw(
				type = errorType,
				message = "IPInfo.io responded with a non-200 status code.",
				detail = "The HTTP response came back with status code [#apiResponse.statusCode#].",
				extendedInfo = content
			);

		}

		return( content );

	}


	/**
	* I safely access the given key on the given struct, returning either the value (if
	* the key exists) or an empty string if the key doesn't exist.
	*
	* @data I am the data being accessed.
	* @key I am the key being accessed.
	* @output false
	*/
	private string function getValueSafely(
		required struct data,
		required string key
		) {

		if ( structKeyExists( data, key ) ) {

			return( data[ key ] );

		}

		return( "" );

	}


	/**
	* I return a normalized representation of the IP info. This way, the response
	* structure will always be the same, even if IPInfo doesn't necessarily have all of
	* the relevant information for the provided IP address.
	*
	* Any field not provided by IPInfo will be normalized as an empty string.
	*
	* @ipInfo I am the structured data returned from the ipinfo.io end-point.
	* @output false
	*/
	private struct function normalizeStructuredData( required struct ipInfo ) {

		var normalizedInfo = {
			"ip": getValueSafely( ipInfo, "ip" ),
			"city": getValueSafely( ipInfo, "city" ),
			"postal": getValueSafely( ipInfo, "postal" ),
			"region": getValueSafely( ipInfo, "region" ),
			"country": getValueSafely( ipInfo, "country" ),
			"hostname": getValueSafely( ipInfo, "hostname" ),
			"org": getValueSafely( ipInfo, "org" ),
			"loc": getValueSafely( ipInfo, "loc" ),
			"latitude": "",
			"longitude": ""
		};

		// IPInfo doesn't break out the "loc" field; but, the majority of use cases
		// will certainly want to do that. As such, let's parse it into individual
		// latitude and longitude values (when available).
		if ( listLen( normalizedInfo.loc ) == 2 ) {

			var coordinates = listToArray( normalizedInfo.loc );
			normalizedInfo.latitude = coordinates[ 1 ];
			normalizedInfo.longitude = coordinates[ 2 ];

		}

		// Sometimes, IPInfo includes the "bogon" flag:
		// --
		// (from Wikipedia) Bogon is also an informal name for an IP packet on the public
		// Internet that claims to be from an area of the IP address space (or network
		// prefix or network block) reserved, but not yet allocated or delegated by the
		// Internet Assigned Numbers Authority (IANA) or a delegated Regional Internet
		// Registry (RIR).
		// --
		// If that is the case, IPInfo will report "bogon: 1". Let's normalize that to a
		// Boolean value.
		normalizedInfo[ "bogon" ] = ( getValueSafely( ipInfo, "bogon" ) == "1" );

		return( normalizedInfo );

	}

}