SDKs overview

Telize offers a dedicated software development kit (SDK) to streamline the process of integrating its IP Geolocation API into applications. An SDK typically includes libraries, code samples, documentation, and tools that assist developers in building applications for a specific platform or programming language Google Developers SDK Terms. For Telize, the primary SDK is a client-side JavaScript library designed for web-based applications.

The Telize IP Geolocation API allows developers to retrieve geographical information—such as country, city, and coordinates—associated with an IP address. This functionality is used in various applications, including content geo-targeting, website personalization, and fraud detection. The official JavaScript SDK simplifies making these API calls, handling aspects like request formatting and response parsing, thereby reducing the boilerplate code required by developers.

While Telize's official support focuses on JavaScript, the API itself is a standard HTTP-based REST API. This means that developers can interact with the API using any programming language capable of making HTTP requests, even in the absence of an official SDK for that specific language. Community-contributed libraries often emerge to provide wrappers or helper functions for popular languages, further extending the API's accessibility.

Official SDKs by language

Telize provides an official JavaScript SDK to facilitate integration with its IP Geolocation API. This SDK is designed for client-side web applications, enabling developers to embed geolocation functionality directly into their web pages. The library abstracts the underlying HTTP requests, allowing developers to focus on application logic rather than low-level API communication. The Telize documentation provides detailed instructions and examples for utilizing this SDK Telize API Documentation.

The following table summarizes the key characteristics of the official Telize SDK:

Language Package/Library Name Installation Method Maturity
JavaScript telize-js (or direct script include) <script src="//telize.com/javascript/telize.js"></script> Stable

The JavaScript SDK is maintained by Telize and is considered the primary method for client-side integration. It simplifies access to the core IP Geolocation API, which returns data in JSON format, making it readily consumable by JavaScript applications.

Installation

The official Telize JavaScript SDK is primarily designed for direct inclusion in web pages. This method requires no package manager or build step, making it straightforward to add geolocation capabilities to existing web projects.

JavaScript (Direct Script Include)

To install the Telize JavaScript library, you typically include it directly within your HTML file using a <script> tag. This loads the library asynchronously from Telize's content delivery network (CDN).

Steps:

  1. Add the script tag: Place the following script tag within the <head> or before the closing </body> tag of your HTML document. Positioning it before the closing </body> tag is often recommended for performance, as it allows the rest of your page to load first.
<script src="//telize.com/javascript/telize.js"></script>

Once the script is loaded, the Telize object becomes globally available in your JavaScript environment. You can then use its methods to interact with the IP Geolocation API. For more detailed instructions and alternative loading methods, refer to the Telize documentation portal.

Quickstart example

This quickstart example demonstrates how to use the Telize JavaScript SDK to retrieve the geographical location based on the client's IP address and display it on a web page. This example assumes you have already included the Telize JavaScript library as described in the installation section.

JavaScript Example

This example sets up a simple HTML page that fetches and displays the user's country and city using the Telize API via the included JavaScript library.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Telize Geolocation Example</title>
</head>
<body>
    <h1>Your Geolocation Information</h1>
    <p>Country: <strong id="country">Loading...</strong></p>
    <p>City: <strong id="city">Loading...</strong></p>

    <script src="//telize.com/javascript/telize.js"></script>
    <script>
        // Ensure the Telize object is available after the script loads
        window.onload = function() {
            if (typeof Telize !== 'undefined') {
                Telize.geoip(function(json) {
                    const countryElement = document.getElementById('country');
                    const cityElement = document.getElementById('city');

                    if (json && json.country_name && json.city) {
                        countryElement.textContent = json.country_name;
                        cityElement.textContent = json.city;
                    } else {
                        countryElement.textContent = 'Not available';
                        cityElement.textContent = 'Not available';
                        console.error('Failed to retrieve geolocation data:', json);
                    }
                });
            } else {
                console.error('Telize JavaScript library not loaded.');
                document.getElementById('country').textContent = 'Error loading library';
                document.getElementById('city').textContent = 'Error loading library';
            }
        };
    </script>
</body>
</html>

Explanation:

  1. The HTML structure includes two <p> tags with <strong> elements, which will display the country and city information.
  2. The Telize JavaScript library is loaded via a <script> tag from the Telize CDN.
  3. An inline JavaScript block then waits for the entire page to load (window.onload) to ensure the Telize object is available.
  4. Telize.geoip() is called with a callback function. This function executes once the geolocation data is successfully retrieved from the Telize API.
  5. Inside the callback, the json parameter contains the geolocation data. We access json.country_name and json.city to update the respective HTML elements.
  6. Error handling is included to display 'Not available' if data retrieval fails or if the Telize library doesn't load correctly.

This example demonstrates a basic client-side geolocation lookup. For server-side applications or more complex scenarios, direct HTTP requests to the Telize API may be preferred, as the official JavaScript SDK is primarily designed for browser environments.

Community libraries

While Telize maintains an official JavaScript SDK for client-side integration, the underlying Telize IP Geolocation API is a standard RESTful API. This means it communicates over HTTP and typically returns data in JSON format Mozilla MDN Web Docs on REST. Because of this architectural design, developers are not limited to using only the official SDK. They can interact with the API using standard HTTP client libraries available in virtually any programming language.

Community-driven efforts often result in unofficial libraries or wrappers that simplify interaction with popular APIs in languages where no official SDK exists. These libraries can provide:

  • Language-specific idioms: Adapting the API interaction to the common patterns and best practices of a particular language (e.g., Python, Ruby, PHP, Java, Go).
  • Convenience functions: Abstracting HTTP requests, handling JSON parsing, and managing potential API keys or rate limits.
  • Improved error handling: Providing more structured error reporting than raw HTTP status codes.

As of the current information, Telize's primary focus for SDKs is the client-side JavaScript library. Developers looking for wrappers in other languages are encouraged to search public code repositories (such as GitHub) for community-contributed projects. These projects might offer similar convenience as an official SDK, but their maintenance, support, and adherence to API changes can vary. When utilizing community libraries, it is advisable to:

  • Review the source code: To ensure it aligns with security best practices and correctly implements the API specifications.
  • Check for active maintenance: Libraries that are regularly updated are more likely to support the latest API versions and address potential bugs.
  • Consult documentation and examples: To understand how to use the library effectively and integrate it into your project.

For server-side applications, direct HTTP requests using native language features or general-purpose HTTP client libraries (e.g., fetch in Node.js, requests in Python, HttpClient in Java) are a reliable and often straightforward approach to consuming the Telize API without relying on specific wrappers.