GeoIPAPI 0.0.1

<div align="center"> <img src="https://via.placeholder.com/400x150/0066cc/ffffff?text=GeoIP+SDK" alt="GeoIP SDK Logo" />

GeoIP C# SDK

Developer-friendly & type-safe C# SDK for enterprise IP geolocation services

<div align="center"> <a href="https://opensource.org/licenses/MIT"> <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /> </a> <img src="https://img.shields.io/badge/.NET-6.0+-purple.svg" alt=".NET 6.0+" /> <img src="https://img.shields.io/badge/C%23-10.0+-blue.svg" alt="C# 10.0+" /> <img src="https://img.shields.io/badge/Status-Beta-orange.svg" alt="Beta Status" /> </div> </div>

<br />

🌍 Overview

The GeoIP C# SDK provides a powerful, enterprise-grade solution for IP geolocation services. Built with modern C# practices and type safety in mind, this SDK enables developers to seamlessly integrate real-time IP geolocation data into their applications for personalization, analytics, fraud detection, and security purposes.

✨ Key Features

• 🎯 Type-Safe: Full IntelliSense support with strongly typed models
• 🚀 High Performance: Optimized for enterprise-scale applications
• 🔧 Easy Integration: Simple, intuitive API design
• 📊 Multiple Formats: Support for JSON, JSONP, XML, and YAML responses
• 🛡️ Enterprise Ready: Built for production environments with comprehensive error handling
• ⚡ Async/Await: Full support for modern asynchronous programming patterns
• 🌐 Flexible Configuration: Customizable server endpoints and request parameters

🎯 Use Cases

• Content Personalization: Deliver location-specific content and experiences
• Analytics & Insights: Geographic analysis of user traffic and behavior
• Security & Fraud Detection: IP-based threat detection and prevention
• Compliance: Geographic restrictions and regulatory compliance
• Load Balancing: Route users to nearest servers based on location

Summary

GeoIPAPI.com - Enterprise IP Geolocation: A high-performance, enterprise-grade IP Geolocation API providing real-time data for personalization, analytics, and security. Supports JSON, JSONP, XML, and YAML formats.

📚 Table of Contents

• 🌍 Overview
• 🚀 Installation
• 📖 Quick Start
• 🔧 Available Operations
• 📁 Project Structure
• ⚙️ Configuration
• ❌ Error Handling
• 🌐 Server Selection
• 🧪 Testing
• 🤝 Contributing
• 🛠️ Development
• 📄 License
• 🙏 Credits

🚀 Installation

Package Manager Console

Install the package using the Package Manager Console in Visual Studio:

Install-Package GeoIP

.NET CLI

Install using the .NET CLI:

dotnet add package GeoIP

PackageReference

Add a PackageReference to your project file:

<PackageReference Include="GeoIP" Version="1.0.0" />

Local Development

To add a reference to a local instance of the SDK in a .NET project:

dotnet add reference src/GeoIP/GeoIP.csproj

Requirements

• .NET 6.0 or later
• C# 10.0 or later

📖 Quick Start

Basic Usage

using GeoIP;

var sdk = new GeoIp();

var res = await sdk.GeoIPEndpoints.GetIpAsync();

// handle response

Advanced Usage

using GeoIP;
using GeoIP.Models.Errors;

var sdk = new GeoIp(serverUrl: "https://api.geoipapi.com");

try
{
    // Get current IP address
    var currentIp = await sdk.GeoIPEndpoints.GetIpAsync();
    Console.WriteLine($"Current IP: {currentIp}");
    
    // Get detailed geolocation data
    var geoData = await sdk.GeoIPEndpoints.GetIpDataAsync();
    Console.WriteLine($"Location: {geoData.Country}, {geoData.City}");
}
catch (HTTPValidationError validationError)
{
    Console.WriteLine($"Validation error: {validationError.Message}");
}
catch (APIException apiError)
{
    Console.WriteLine($"API error: {apiError.Message}");
}

🔧 Available Operations

<details open> <summary>Available methods</summary>

GeoIPEndpoints

• GetIp - Get Current IP Address
• GetIpData - Get Json Data from IP Address

</details>

📁 Project Structure

geo-ip-csharp/
├── src/
│   └── GeoIP/
│       ├── Models/         # Data models and DTOs
│       ├── Endpoints/      # API endpoint implementations
│       ├── Errors/         # Custom exception types
│       └── GeoIP.csproj    # Project file
├── tests/
│   └── GeoIP.Tests/        # Unit and integration tests
├── docs/
│   └── sdks/               # SDK documentation
├── README.md               # This file
└── LICENSE                 # MIT License

Key Components

• Models/: Contains strongly-typed data models for API responses
• Endpoints/: Implementation of API endpoints and HTTP client logic
• Errors/: Custom exception types for different error scenarios
• Tests/: Comprehensive test suite for SDK functionality

⚙️ Configuration

Environment Variables

The SDK supports the following configuration options:

Custom Configuration

var sdk = new GeoIp(
    serverUrl: "https://custom-api.example.com",
    timeout: TimeSpan.FromSeconds(60)
);

❌ Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or throw an exception.

By default, an API error will raise a GeoIP.Models.Errors.APIException exception, which has the following properties:

When custom error responses are specified for an operation, the SDK may also throw their associated exceptions. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the GetIpDataAsync method throws the following exceptions:

Example

using GeoIP;
using GeoIP.Models.Errors;

var sdk = new GeoIp();

try
{
    var res = await sdk.GeoIPEndpoints.GetIpDataAsync();

    // handle response
}
catch (Exception ex)
{
    if (ex is HTTPValidationError)
    {
        // Handle exception data
        throw;
    }
    else if (ex is GeoIP.Models.Errors.APIException)
    {
        // Handle default exception
        throw;
    }
}

🌐 Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverUrl: string optional parameter when initializing the SDK client instance. For example:

using GeoIP;

var sdk = new GeoIp(serverUrl: "https://api.geoipapi.com");

var res = await sdk.GeoIPEndpoints.GetIpAsync();

// handle response

🧪 Testing

Running Tests

Execute the test suite using the .NET CLI:

# Run all tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test category
dotnet test --filter Category=Integration

Test Structure

• Unit Tests: Test individual components in isolation
• Integration Tests: Test API interactions with mock servers
• End-to-End Tests: Test complete workflows against live API

Test Coverage

The SDK maintains high test coverage across all components:

• Models and serialization
• Error handling scenarios
• API endpoint functionality
• Configuration validation

🤝 Contributing

We welcome contributions to the GeoIP C# SDK! Here's how you can help:

Development Setup

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/your-username/geo-ip-csharp.git
   cd geo-ip-csharp
   

3. Install dependencies:

   dotnet restore
   

4. Create a feature branch:

   git checkout -b feature/your-feature-name
   

Code Guidelines

• Follow C# coding conventions and best practices
• Maintain test coverage above 90%
• Use meaningful commit messages
• Update documentation for new features
• Ensure all tests pass before submitting PR

Pull Request Process

1. Update tests for any new functionality
2. Update documentation as needed
3. Ensure CI pipeline passes
4. Request review from maintainers

🛠️ Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

Built With

• .NET 6+ - Modern .NET platform
• System.Text.Json - High-performance JSON serialization
• Microsoft.Extensions.Http - HTTP client factory and configuration

Acknowledgements

• Thanks to the GeoIPAPI.com team for providing the robust geolocation service
• Inspired by modern SDK design patterns and developer experience best practices
• Community feedback and contributions that help improve this SDK

<div align="center">

Ready to get started? Install the SDK and begin integrating IP geolocation into your applications today!

⭐ Like this project? Give it a star on GitHub and help others discover it!

🐛 Found an issue? Open an issue and let us know!

💡 Have a feature request? We'd love to hear your ideas!

</div>