271 lines
9.2 KiB
Zig
271 lines
9.2 KiB
Zig
//! OpenFIGI API provider -- maps CUSIPs (and other identifiers) to ticker symbols.
|
|
//! API docs: https://www.openfigi.com/api/documentation
|
|
//!
|
|
//! Free tier: 25 requests/minute with API key (each request can contain up to 100 jobs).
|
|
//! No API key required for basic use (lower rate limits).
|
|
//!
|
|
//! Note: OpenFIGI does NOT cover most mutual funds (especially institutional/401(k) share
|
|
//! classes). For those, use the `ticker::` alias field in the portfolio SRF file.
|
|
|
|
const std = @import("std");
|
|
|
|
const api_url = "https://api.openfigi.com/v3/mapping";
|
|
|
|
/// Result of a CUSIP lookup.
|
|
pub const FigiResult = struct {
|
|
ticker: ?[]const u8,
|
|
name: ?[]const u8,
|
|
security_type: ?[]const u8,
|
|
/// Whether the API returned a valid response (even if no match was found)
|
|
found: bool,
|
|
};
|
|
|
|
/// Look up a single CUSIP via OpenFIGI. Caller must free returned strings.
|
|
/// Returns null ticker if not found. Uses system curl for the POST request.
|
|
pub fn lookupCusip(
|
|
allocator: std.mem.Allocator,
|
|
cusip: []const u8,
|
|
api_key: ?[]const u8,
|
|
) !FigiResult {
|
|
const results = try lookupCusips(allocator, &.{cusip}, api_key);
|
|
defer {
|
|
for (results) |r| {
|
|
if (r.ticker) |t| allocator.free(t);
|
|
if (r.name) |n| allocator.free(n);
|
|
if (r.security_type) |s| allocator.free(s);
|
|
}
|
|
allocator.free(results);
|
|
}
|
|
if (results.len == 0) return .{ .ticker = null, .name = null, .security_type = null, .found = false };
|
|
|
|
// Copy results since we're freeing the batch
|
|
const r = results[0];
|
|
return .{
|
|
.ticker = if (r.ticker) |t| try allocator.dupe(u8, t) else null,
|
|
.name = if (r.name) |n| try allocator.dupe(u8, n) else null,
|
|
.security_type = if (r.security_type) |s| try allocator.dupe(u8, s) else null,
|
|
.found = r.found,
|
|
};
|
|
}
|
|
|
|
/// Look up multiple CUSIPs in a single batch request. Caller owns all returned slices.
|
|
/// Results array is parallel to the input cusips array (same length, same order).
|
|
pub fn lookupCusips(
|
|
allocator: std.mem.Allocator,
|
|
cusips: []const []const u8,
|
|
api_key: ?[]const u8,
|
|
) ![]FigiResult {
|
|
if (cusips.len == 0) return try allocator.alloc(FigiResult, 0);
|
|
|
|
// Build JSON request body: [{"idType":"ID_CUSIP","idValue":"..."},...]
|
|
var body_buf: std.ArrayList(u8) = .empty;
|
|
defer body_buf.deinit(allocator);
|
|
|
|
try body_buf.append(allocator, '[');
|
|
for (cusips, 0..) |cusip, i| {
|
|
if (i > 0) try body_buf.append(allocator, ',');
|
|
try body_buf.appendSlice(allocator, "{\"idType\":\"ID_CUSIP\",\"idValue\":\"");
|
|
try body_buf.appendSlice(allocator, cusip);
|
|
try body_buf.appendSlice(allocator, "\"}");
|
|
}
|
|
try body_buf.append(allocator, ']');
|
|
|
|
const body_str = body_buf.items;
|
|
|
|
// Build curl command
|
|
var argv_buf: [12][]const u8 = undefined;
|
|
var argc: usize = 0;
|
|
argv_buf[argc] = "curl";
|
|
argc += 1;
|
|
argv_buf[argc] = "-sS";
|
|
argc += 1;
|
|
argv_buf[argc] = "-f";
|
|
argc += 1;
|
|
argv_buf[argc] = "--max-time";
|
|
argc += 1;
|
|
argv_buf[argc] = "30";
|
|
argc += 1;
|
|
argv_buf[argc] = "-X";
|
|
argc += 1;
|
|
argv_buf[argc] = "POST";
|
|
argc += 1;
|
|
argv_buf[argc] = "-H";
|
|
argc += 1;
|
|
argv_buf[argc] = "Content-Type: application/json";
|
|
argc += 1;
|
|
if (api_key) |key| {
|
|
// Build header string: "X-OPENFIGI-APIKEY: <key>"
|
|
const hdr = try std.fmt.allocPrint(allocator, "X-OPENFIGI-APIKEY: {s}", .{key});
|
|
defer allocator.free(hdr);
|
|
argv_buf[argc] = "-H";
|
|
argc += 1;
|
|
argv_buf[argc] = hdr;
|
|
argc += 1;
|
|
argv_buf[argc] = "-d";
|
|
argc += 1;
|
|
|
|
// Need to add body and URL — but we've used all slots for the -H key header.
|
|
// Restructure: use a dynamic list.
|
|
var argv_list: std.ArrayList([]const u8) = .empty;
|
|
defer argv_list.deinit(allocator);
|
|
try argv_list.appendSlice(allocator, &.{
|
|
"curl", "-sS", "--max-time", "30",
|
|
"-X", "POST",
|
|
"-H", "Content-Type: application/json",
|
|
"-H", hdr,
|
|
"-d", body_str,
|
|
api_url,
|
|
});
|
|
|
|
const result = std.process.Child.run(.{
|
|
.allocator = allocator,
|
|
.argv = argv_list.items,
|
|
.max_output_bytes = 1 * 1024 * 1024,
|
|
}) catch return error.RequestFailed;
|
|
defer allocator.free(result.stderr);
|
|
|
|
const success = switch (result.term) {
|
|
.Exited => |code| code == 0,
|
|
else => false,
|
|
};
|
|
if (!success) {
|
|
allocator.free(result.stdout);
|
|
return error.RequestFailed;
|
|
}
|
|
return parseResponse(allocator, result.stdout, cusips.len);
|
|
} else {
|
|
// No API key
|
|
var argv_list: std.ArrayList([]const u8) = .empty;
|
|
defer argv_list.deinit(allocator);
|
|
try argv_list.appendSlice(allocator, &.{
|
|
"curl", "-sS", "--max-time", "30",
|
|
"-X", "POST",
|
|
"-H", "Content-Type: application/json",
|
|
"-d", body_str,
|
|
api_url,
|
|
});
|
|
|
|
const result = std.process.Child.run(.{
|
|
.allocator = allocator,
|
|
.argv = argv_list.items,
|
|
.max_output_bytes = 1 * 1024 * 1024,
|
|
}) catch return error.RequestFailed;
|
|
defer allocator.free(result.stderr);
|
|
|
|
const success = switch (result.term) {
|
|
.Exited => |code| code == 0,
|
|
else => false,
|
|
};
|
|
if (!success) {
|
|
allocator.free(result.stdout);
|
|
return error.RequestFailed;
|
|
}
|
|
return parseResponse(allocator, result.stdout, cusips.len);
|
|
}
|
|
}
|
|
|
|
fn parseResponse(allocator: std.mem.Allocator, body: []const u8, expected_count: usize) ![]FigiResult {
|
|
defer allocator.free(body);
|
|
|
|
const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch
|
|
return error.ParseError;
|
|
defer parsed.deinit();
|
|
|
|
const root = parsed.value;
|
|
const arr = switch (root) {
|
|
.array => |a| a,
|
|
else => return error.ParseError,
|
|
};
|
|
|
|
var results = try allocator.alloc(FigiResult, expected_count);
|
|
for (results) |*r| r.* = .{ .ticker = null, .name = null, .security_type = null, .found = false };
|
|
|
|
for (arr.items, 0..) |item, i| {
|
|
if (i >= expected_count) break;
|
|
|
|
const obj = switch (item) {
|
|
.object => |o| o,
|
|
else => continue,
|
|
};
|
|
|
|
// Check for error/warning (no match)
|
|
if (obj.get("warning") != null or obj.get("error") != null) {
|
|
results[i].found = true; // API responded, just no match
|
|
continue;
|
|
}
|
|
|
|
// Get the data array
|
|
const data = switch (obj.get("data") orelse continue) {
|
|
.array => |a| a,
|
|
else => continue,
|
|
};
|
|
|
|
if (data.items.len == 0) {
|
|
results[i].found = true;
|
|
continue;
|
|
}
|
|
|
|
// Use the first result, preferring exchCode "US" if available
|
|
var best: ?std.json.ObjectMap = null;
|
|
for (data.items) |entry| {
|
|
const entry_obj = switch (entry) {
|
|
.object => |o| o,
|
|
else => continue,
|
|
};
|
|
if (best == null) best = entry_obj;
|
|
// Prefer US exchange
|
|
if (entry_obj.get("exchCode")) |ec| {
|
|
if (ec == .string and std.mem.eql(u8, ec.string, "US")) {
|
|
best = entry_obj;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
if (best) |b| {
|
|
results[i].found = true;
|
|
if (b.get("ticker")) |t| {
|
|
if (t == .string and t.string.len > 0) {
|
|
results[i].ticker = try allocator.dupe(u8, t.string);
|
|
}
|
|
}
|
|
if (b.get("name")) |n| {
|
|
if (n == .string and n.string.len > 0) {
|
|
results[i].name = try allocator.dupe(u8, n.string);
|
|
}
|
|
}
|
|
if (b.get("securityType")) |st| {
|
|
if (st == .string and st.string.len > 0) {
|
|
results[i].security_type = try allocator.dupe(u8, st.string);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
return results;
|
|
}
|
|
|
|
/// Check if a string looks like a CUSIP (9 alphanumeric characters).
|
|
/// CUSIPs have 6 alphanumeric issuer chars + 2 issue chars + 1 check digit.
|
|
/// This is a heuristic — it won't catch all CUSIPs and may have false positives.
|
|
pub fn isCusipLike(s: []const u8) bool {
|
|
if (s.len != 9) return false;
|
|
// Must contain at least one digit (all-alpha would be a ticker)
|
|
var has_digit = false;
|
|
for (s) |c| {
|
|
if (!std.ascii.isAlphanumeric(c)) return false;
|
|
if (std.ascii.isDigit(c)) has_digit = true;
|
|
}
|
|
return has_digit;
|
|
}
|
|
|
|
test "isCusipLike" {
|
|
try std.testing.expect(isCusipLike("02315N600")); // Vanguard Target 2035
|
|
try std.testing.expect(isCusipLike("02315N709")); // Vanguard Target 2040
|
|
try std.testing.expect(isCusipLike("459200101")); // IBM
|
|
try std.testing.expect(isCusipLike("06051XJ45")); // CD CUSIP
|
|
try std.testing.expect(!isCusipLike("AAPL")); // Too short
|
|
try std.testing.expect(!isCusipLike("ABCDEFGHI")); // No digits
|
|
try std.testing.expect(isCusipLike("NON40OR52")); // Looks cusip-like (has digits, 9 chars)
|
|
try std.testing.expect(!isCusipLike("12345")); // Too short
|
|
}
|