386 lines
12 KiB
Zig
386 lines
12 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;
|
|
}
|
|
|
|
// -- Tests --
|
|
|
|
test "parseResponse basic single CUSIP" {
|
|
const allocator = std.testing.allocator;
|
|
|
|
// parseResponse takes ownership of body (frees it), so we must dupe
|
|
const body = try allocator.dupe(u8,
|
|
\\[
|
|
\\ {
|
|
\\ "data": [
|
|
\\ {"ticker": "AAPL", "name": "APPLE INC", "securityType": "Common Stock", "exchCode": "US"}
|
|
\\ ]
|
|
\\ }
|
|
\\]
|
|
);
|
|
|
|
const results = try parseResponse(allocator, body, 1);
|
|
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);
|
|
}
|
|
|
|
try std.testing.expectEqual(@as(usize, 1), results.len);
|
|
try std.testing.expect(results[0].found);
|
|
try std.testing.expectEqualStrings("AAPL", results[0].ticker.?);
|
|
try std.testing.expectEqualStrings("APPLE INC", results[0].name.?);
|
|
try std.testing.expectEqualStrings("Common Stock", results[0].security_type.?);
|
|
}
|
|
|
|
test "parseResponse prefers US exchange" {
|
|
const allocator = std.testing.allocator;
|
|
|
|
const body = try allocator.dupe(u8,
|
|
\\[
|
|
\\ {
|
|
\\ "data": [
|
|
\\ {"ticker": "AAPL-DE", "name": "APPLE INC", "securityType": "Common Stock", "exchCode": "GY"},
|
|
\\ {"ticker": "AAPL", "name": "APPLE INC", "securityType": "Common Stock", "exchCode": "US"}
|
|
\\ ]
|
|
\\ }
|
|
\\]
|
|
);
|
|
|
|
const results = try parseResponse(allocator, body, 1);
|
|
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);
|
|
}
|
|
|
|
try std.testing.expectEqualStrings("AAPL", results[0].ticker.?);
|
|
}
|
|
|
|
test "parseResponse warning (no match)" {
|
|
const allocator = std.testing.allocator;
|
|
|
|
const body = try allocator.dupe(u8,
|
|
\\[
|
|
\\ {
|
|
\\ "warning": "No identifier found."
|
|
\\ }
|
|
\\]
|
|
);
|
|
|
|
const results = try parseResponse(allocator, body, 1);
|
|
defer allocator.free(results);
|
|
|
|
try std.testing.expectEqual(@as(usize, 1), results.len);
|
|
try std.testing.expect(results[0].found); // API responded, just no match
|
|
try std.testing.expect(results[0].ticker == null);
|
|
}
|
|
|
|
test "parseResponse multiple CUSIPs" {
|
|
const allocator = std.testing.allocator;
|
|
|
|
const body = try allocator.dupe(u8,
|
|
\\[
|
|
\\ {
|
|
\\ "data": [
|
|
\\ {"ticker": "AAPL", "name": "APPLE INC", "securityType": "Common Stock", "exchCode": "US"}
|
|
\\ ]
|
|
\\ },
|
|
\\ {
|
|
\\ "warning": "No identifier found."
|
|
\\ },
|
|
\\ {
|
|
\\ "data": [
|
|
\\ {"ticker": "MSFT", "name": "MICROSOFT CORP", "securityType": "Common Stock", "exchCode": "US"}
|
|
\\ ]
|
|
\\ }
|
|
\\]
|
|
);
|
|
|
|
const results = try parseResponse(allocator, body, 3);
|
|
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);
|
|
}
|
|
|
|
try std.testing.expectEqual(@as(usize, 3), results.len);
|
|
|
|
// First: AAPL
|
|
try std.testing.expect(results[0].found);
|
|
try std.testing.expectEqualStrings("AAPL", results[0].ticker.?);
|
|
|
|
// Second: no match
|
|
try std.testing.expect(results[1].found);
|
|
try std.testing.expect(results[1].ticker == null);
|
|
|
|
// Third: MSFT
|
|
try std.testing.expect(results[2].found);
|
|
try std.testing.expectEqualStrings("MSFT", results[2].ticker.?);
|
|
}
|
|
|
|
test "parseResponse empty data array" {
|
|
const allocator = std.testing.allocator;
|
|
|
|
const body = try allocator.dupe(u8,
|
|
\\[
|
|
\\ {
|
|
\\ "data": []
|
|
\\ }
|
|
\\]
|
|
);
|
|
|
|
const results = try parseResponse(allocator, body, 1);
|
|
defer allocator.free(results);
|
|
|
|
try std.testing.expectEqual(@as(usize, 1), results.len);
|
|
try std.testing.expect(results[0].found);
|
|
try std.testing.expect(results[0].ticker == null);
|
|
}
|