SDKs & samples¶

13 official SDKs, one contract. Each implements the 14 endpoints with typed models, Page<T> paging and typed 401/404/429 errors, and is pinned by a contract test replaying the same recorded fixtures in CI.

SDK	Install	Docs page
JavaScript / TypeScript	`npm install /path/to/nationkit/sdks/js`	#javascript
Python	`pip install git+…#subdirectory=sdks/python`	#python
Go	`go get github.com/ibhar-tech/nationkit/sdks/go`	#go
Rust	git dependency in `Cargo.toml`	#rust
Java	`mvn install` from `sdks/java`	#java
Kotlin (JVM/Android)	`./gradlew publishToMavenLocal`	#kotlin
C# / .NET	`<ProjectReference>` / `dotnet pack`	#c-dotnet
PHP (+ Laravel)	Composer path repository	#php-laravel
Ruby (+ Rails)	gemspec git dependency	#ruby
Dart / Flutter	git dependency in `pubspec.yaml`	#dart-flutter
Elixir	path dependency (OTP 27+)	#elixir
Scala	sbt publishLocal (JDK 17+)	#scala
Perl	`PERL5LIB` (core-only, 5.20+)	#perl

Package registries

SDKs currently install from this GitHub repository (clone/path/git). Registry publishing (npm, PyPI, crates.io, …) is on the roadmap; the git installs are production-stable and versioned at 1.4.0.

Every snippet below does the same three things: build a client with your key, fetch Algeria's 69 wilayas (paged), and run a multilingual search.

JavaScript¶

Install: npm install /path/to/nationkit/sdks/js (TypeScript sources, builds on install).

import { NationKitClient, NotFoundError, RateLimitedError, NationKitError } from "nationkit";

const client = new NationKitClient({
  apiKey: process.env.NATIONKIT_API_KEY,
  // baseUrl: "https://api.nationkit.site",  timeoutMs: 10_000
});

const page = await client.getDivisions("dz", { level: 1, perPage: 2500 });
console.log(page.total, page.items[0].names.ar);

const hits = await client.search("dz", "adrar"); // sorted by matchScore desc

try { await client.getCountry("xx"); }
catch (err) {
  if (err instanceof NotFoundError) console.log("no such country");
  else if (err instanceof RateLimitedError) console.log("retry in", err.retryAfterSeconds);
  else if (err instanceof NationKitError) console.log(err.status, err.message);
}

Python¶

Install: pip install "git+https://github.com/ibhar-tech/nationkit.git#subdirectory=sdks/python"

from nationkit import NationKitClient, NotFoundError, RateLimitedError

client = NationKitClient(api_key="nk_live_...")   # base_url/timeout optional

page = client.get_divisions("dz", level=1, per_page=2500)
print(page.total, page.items[0].names["ar"])

hits = client.search("dz", "adrar")

try:
    client.get_country("xx")
except RateLimitedError as e:
    print("retry in", e.retry_after_seconds)
except NotFoundError:
    print("no such country")

Go¶

Install: go get github.com/ibhar-tech/nationkit/sdks/go (stdlib-only client).

import nationkit "github.com/ibhar-tech/nationkit/sdks/go"

client := nationkit.NewClient("nk_live_...")
page, err := client.GetDivisions(ctx, "dz", nationkit.DivisionsQuery{Level: 1, PerPage: 2500})
if err != nil { log.Fatal(err) }
fmt.Println(page.Total, page.Items[0].Names["ar"])

hits, _ := client.Search(ctx, "dz", "adrar")

_, err = client.GetCountry(ctx, "xx") // *nationkit.NotFoundError / RateLimitedError / ApiError

Rust¶

Install: nationkit = { git = "https://github.com/ibhar-tech/nationkit.git" } (reqwest + rustls).

use nationkit::{DivisionsQuery, NationKitClient};

let client = NationKitClient::new("nk_live_...")?;
let page = client.get_divisions("dz", &DivisionsQuery::new().level(1).per_page(2500)).await?;
println!("{} {}", page.total, page.items[0].names["ar"]);

let hits = client.search("dz", "adrar").await?;   // typed NotFoundError/RateLimitedError/ApiError

Java¶

Install: mvn install from sdks/java (Jackson is the only dependency).

import dev.nationkit.*;

var client = new NationKitClient("nk_live_...");
Page<Division> page = client.getDivisions("dz", DivisionQuery.of().withLevel(1).withPerPage(2500));
System.out.println(page.total() + " " + page.items().get(0).names().get("ar"));

List<SearchResult> hits = client.search("dz", "adrar");

Kotlin¶

Install: ./gradlew publishToMavenLocal from sdks/kotlin (Ktor client; Android-ready).

import com.nationkit.*

val client = NationKitClient(apiKey = "nk_live_...")
client.use {
    val page = client.getDivisions("dz", level = 1)
    println("${page.total} ${page.items.first().names["ar"]}")
    val hits = client.search("dz", "adrar")
}

C# / .NET¶

Install: <ProjectReference> to sdks/dotnet/NationKit.Client.csproj or dotnet pack.

using NationKit.Client;

using var client = new NationKitClient("nk_live_...");
Page<Division> page = await client.GetDivisionsAsync("dz", level: 1, perPage: 2500);
Console.WriteLine($"{page.Total} {page.Items[0].Names["ar"]}");

IReadOnlyList<SearchResult> hits = await client.SearchAsync("dz", "adrar");

PHP / Laravel¶

Install: Composer path repository pointing at sdks/php in a clone. Ships a Laravel service provider + NationKit facade.

use NationKit\NationKitClient;

$client = new NationKitClient(apiKey: getenv('NATIONKIT_API_KEY'));
$wilayas = $client->getDivisions('dz', level: 1, perPage: 2500);
echo $wilayas->total, ' ', $wilayas->items[0]->names['ar'];

$hits = $client->search('dz', 'adrar');

Ruby¶

Install: gem 'nationkit', git: 'https://github.com/ibhar-tech/nationkit.git', glob: 'sdks/ruby/*.gemspec'

require 'nationkit'

client = NationKit::Client.new(api_key: ENV['NATIONKIT_API_KEY'])
page = client.get_divisions('dz', level: 1, per_page: 2500)
puts "#{page.total} #{page.items.first.names['ar']}"

client.search('dz', 'adrar').each { |hit| puts hit.match_score }

Dart / Flutter¶

Install: git dependency in pubspec.yaml with path: sdks/dart (ships an Android example app).

import 'package:nationkit/nationkit.dart';

final client = NationKitClient(apiKey: 'nk_live_...');
final page = await client.getDivisions('dz', level: 1);
print('${page.total} ${page.items.first.names['ar']}');
final hits = await client.search('dz', 'adrar');
client.close();

Elixir¶

Install: {:nationkit, path: "path/to/nationkit/sdks/elixir"} — zero dependencies, OTP 27+.

client = NationKit.Client.new("nk_live_...")

{:ok, page} = NationKit.Client.get_divisions(client, "dz", level: 1, per_page: 2500)
IO.puts("#{page.total} #{hd(page.items).names["ar"]}")

{:ok, hits} = NationKit.Client.search(client, "dz", "adrar")
# {:error, exception} — NationKit.Error.status/1 carries the HTTP status

Scala¶

Install: "dev.nationkit" %% "nationkit-scala" % "1.4.0" (sbt publishLocal; JDK 17+).

import dev.nationkit.*

val client = NationKitClient(apiKey = "nk_live_...")
val page = Await.result(client.getDivisions("dz", level = Some(1)), 10.seconds)
println(s"${page.total} ${page.items.head.names("ar")}")

val hits = Await.result(client.search("dz", "adrar"), 10.seconds)
// Futures fail with NationKitError subtypes carrying .status

Perl¶

Install: PERL5LIB=/path/to/nationkit/sdks/perl/lib (zero deps beyond core).

use NationKit;

my $client = NationKit->new(api_key => 'nk_live_...');
my $page = $client->get_divisions('dz', level => 1, per_page => 2500);
print "$page->{total} ", $page->items->[0]->names->{ar}, "\n";

my $hits = $client->search('dz', 'adrar');
# dies with NationKit::NotFoundError / RateLimitedError / ApiError on 4xx