Afrigis.Search.Client 1.0.12

AfriGIS DotNet Search Client

Overview

AfriGIS DotNet Search Client is a .NET library for seamless integration with the AfriGIS Search suite of APIs. It provides robust, strongly-typed, and async access to Autocomplete, Geocode, Place Details, and Delivery Address Format APIs, handling authentication, request formatting, and error mapping for you.

• Token-based authentication (OAuth2)
• Strongly-typed request/response models
• Async API for scalable apps
• Comprehensive error handling
• Thread-safe and production-ready

Installation

Install via NuGet:

dotnet add package AfriGIS.DotnetSearchClient

Configuration

The library does not dictate how you store your credentials. You can use appsettings.json, environment variables, or any configuration provider. Example appsettings.json:

{
  "AfriGISOptions": {
    "AuthenticationUrl": "https://auth.afrigis.services",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "ApiKey": "your-api-key"
  }
}

Client Initialization

You can initialize the client using configuration or manual parameters:

// Using Microsoft.Extensions.Configuration
IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

var settings = config.GetRequiredSection("AfriGISOptions").Get<AfriGISOptions>();
// AfriGISOptions is a user-defined POCO (Plain Old CLR Object) that matches your configuration structure.
// For example:
// public class AfriGISOptions {
//     public string AuthenticationUrl { get; set; }
//     public string ClientId { get; set; }
//     public string ClientSecret { get; set; }
//     public string ApiKey { get; set; }
// }

var client = new AfriGISSearchClient(
    settings.ApiKey,
    settings.ClientId,
    settings.ClientSecret,
    settings.AuthenticationUrl
);

Or directly:

var client = new AfriGISSearchClient(
    "your-api-key",
    "your-client-id",
    "your-client-secret",
    "https://auth.afrigis.co.za/oauth2/token"
);

Usage Examples

All endpoints are async and throw exceptions for error conditions. See below for details on which exceptions are thrown and when.

Autocomplete

var autocompleteRequest = new AutocompleteRequest {
    Query = "446 Rigel",
    MaxResults = 5
};
var autocompleteResponse = await client.Autocomplete.GetAsync(autocompleteRequest);
foreach (var suggestion in autocompleteResponse.Result) {
    Console.WriteLine($"{suggestion.Description} ({suggestion.Country})");
}

Geocoding

var geocodeRequest = new GeocodeRequest {
    Query = "446 Rigel Avenue South, Erasmusrand",
    MaxResults = 5
};
var geocodeResponse = await client.Geocode.GetAsync(geocodeRequest);
foreach (var result in geocodeResponse.Result) {
    Console.WriteLine($"{result.FormattedAddress} - {result.Location}");
}

Place Details

string placeReference = "2XIAs5De9f_eEXNFubwV-ZXI41F281017";
var detailsResponse = await client.PlacesDetails.GetAsync(placeReference);
Console.WriteLine(detailsResponse.Result.FormattedAddress);
Console.WriteLine(detailsResponse.Result.Location);

Delivery Address Lookup

string placeReference = "2XIAs5De9f_eEXNFubwV-ZXI41F281017";
var deliveryResponse = await client.Delivery.GetAsync(placeReference);
Console.WriteLine(deliveryResponse.Result.FormattedAddress);
Console.WriteLine(deliveryResponse.Result.DeliveryProp);

Autocomplete (with IncludeTypes/ExcludeTypes)

var autocompleteRequest = new AutocompleteRequest {
    Query = "446 Rigel",
    MaxResults = 5,
    // Include only certain address types (e.g., streets and localities)
    IncludeTypes = new[] {
        RequestAddressTypes.Street_address_level_1,
        RequestAddressTypes.Locality
    },
    // Exclude certain types (e.g., administrative areas)
    ExcludeTypes = new[] {
        RequestAddressTypes.Administrative_area_level_1
    }
};
var autocompleteResponse = await client.Autocomplete.GetAsync(autocompleteRequest);
foreach (var suggestion in autocompleteResponse.Result) {
    Console.WriteLine($"{suggestion.Description} ({suggestion.Country})");
}

Geocoding (with IncludeTypes/ExcludeTypes)

var geocodeRequest = new GeocodeRequest {
    Query = "446 Rigel Avenue South, Erasmusrand",
    MaxResults = 5,
    IncludeTypes = new[] {
        RequestAddressTypes.Street_address_level_1,
        RequestAddressTypes.Locality
    },
    ExcludeTypes = new[] {
        RequestAddressTypes.Administrative_area_level_1
    }
};
var geocodeResponse = await client.Geocode.GetAsync(geocodeRequest);
foreach (var result in geocodeResponse.Result) {
    Console.WriteLine($"{result.FormattedAddress} - {result.Location}");
}

Exception Handling

All endpoints throw exceptions for error conditions:

try {
    var response = await client.Geocode.GetAsync(geocodeRequest);
} catch (AfriGISUnauthorizedException ex) {
    Console.WriteLine($"Auth error: {ex.Message}");
} catch (AfriGISBadRequestException ex) {
    Console.WriteLine($"Bad request: {ex.Message}");
} catch (AfriGISNotFoundException ex) {
    Console.WriteLine($"Not found: {ex.Message}");
} catch (Exception ex) {
    Console.WriteLine($"Other error: {ex.Message}");
}

Error Types

• AfriGISUnauthorizedException: Invalid API key, client ID, or secret.
• AfriGISBadRequestException: Malformed or missing parameters (e.g., empty query).
• AfriGISNotFoundException: Resource not found (e.g., invalid place reference).
• Exception: Network errors, timeouts, or unknown issues.

Thread Safety & Token Management

AfriGISSearchClient is thread-safe and manages authentication tokens automatically. Tokens are refreshed as needed; you do not need to handle this yourself.

Support & Further Resources

• Contact AfriGIS for production support and API documentation