Introduction

This is the documentation for the C# client for Objectia® API. You can find the source code for the client on GitHub. We have API clients in several other programming languages hosted on GitHub.

Requirements

The C# client for Objectia API requires .NET Core 3.0 or later to be installed. You can check if you already have .NET Core installed on your machine by opening up a command prompt or terminal and running the following command:

dotnet --version

You should see something like 3.0.100. If you receive an error message, you can download .NET Core from Microsoft and install it.

Installation

The C# client for Objectia API is published on Nuget, so you can install it with .NET CLI

dotnet add package Objectia --version 1.0.0

or with Package Manager

PM> Install-Package Objectia -Version 1.0.0

Using

Now that we have .NET Core and objectia-csharp installed, we can start using the API. In the example below we will look up the geolocation of the IP address 8.8.8.8.

Create a new folder and create a new console application by typing in:

dotnet new console
dotnet add package Objectia

Edit the file Program.cs so it has the following contents:

using System;
using Objectia;
using Objectia.Api;
using Objectia.Exceptions;

class Program 
{
    static void Main(string[] args)
    {
        var apiKey = Environment.GetEnvironmentVariable("OBJECTIA_APIKEY");
        try 
        {
            ObjectiaClient.Init(apiKey);
            var location = await Api.GeoLocation.GetAsync("8.8.8.8"); 
            Console.WriteLine("Country code: " + location.CountryCode);
        } catch (ResponseException e) {
            Console.WriteLine("Failed to get location");
        }
    }
}

Save the file and enter the following command in terminal:

dotnet run

This will build the application and launch it. It should print the following on your screen:

Country code: US

TIP

If you do not have an API key, you can easily generate one by heading over to the API settings page.

Error handling

The API client will throw an APIException upon error, and you handle the errors in the normal way with a try-catch statement. APIException has three subclasses: APIConnectionException, APITimeoutException and ResponseException.

If you enter an invalid IP address, you will get an exception:

try 
{
    ObjectiaClient.Init(apiKey);
    var location = await Api.GeoLocation.GetAsync("x"); 
} catch (APIConnectionException e) {
    Console.WriteLine("Failed to connect to API server");
} catch (APITimeoutException e) {
    Console.WriteLine("Connection to API server timed out");
} catch (ResponseException e) {
    Console.WriteLine("API request failed:");
    Console.WriteLine("* Status: {0}", e.Status);
    Console.WriteLine("* Code: {0}", e.Code);
    Console.WriteLine("* Message: {0}", e.Message);
}

You should use the Code attribute to determine the reason for the error. The example above will print the following:

API request failed:
* Status: 400
* Code: err-invalid-ip
* Message: Invalid IP address

You can find all the error codes in the REST API documentation.