Go semakin populer untuk alat keuangan kompilasi cepat, kinerja yang dapat diprediksi, dan primitif paralel kelas satu membuatnya cocok untuk pipa data dan otomatisasi perdagangan. Panduan ini berjalan melalui semua yang Anda butuhkan untuk memanggil FXMacroData REST API dari Go, dari permintaan sekali pakai sederhana hingga klien yang dapat digunakan kembali yang menangani timeout, dekoding JSON, dan penyaringan tanggal opsional. Pada akhirnya Anda akan memiliki kode Go idiomatik yang mengambil pengumuman indikator makro, menarik kalender rilis mendatang, dan kueri harga spot FX semuanya dalam kurang dari 150 baris.

Apa yang Akan Anda Bangun

Klien HTTP Go ringan yang mengotentikasi terhadap FXMacroData REST API menggunakan query-parameter API-key auth, mendekode tanggapan JSON terstruktur ke dalam struktur Go yang diketik, dan mengekspos fungsi pembantu yang dapat digunakan kembali untuk tiga keluarga endpoint yang paling umum: pengumuman, kalender rilis, dan tingkat spot FX.

Persyaratan

Go 1.21 atau lebih baru (Go.dev/dl)
Kunci API FXMacroData daftar di /langganan untuk menerima satu
Keterampilan dasar dengan modul Go dan perpustakaan standar

Tidak ada pihak ketiga HTTP atau JSON perpustakaan yang diperlukan standar net/http Dan encoding/json Paket menangani segalanya.

Langkah 1 Memahami Bentuk API

Setiap titik akhir indikator FXMacroData mengikuti pola URL yang sama:

GET https://fxmacrodata.com/api/v1/announcements/{currency}/{indicator}?api_key=YOUR_API_KEY

Tanggapan adalah objek JSON dengan tingkat atas data Setiap elemen berisi date string, angka val, dan opsional announcement_datetime yang memberikan tingkat kedua presisi untuk ketika angka secara resmi dirilis.

curl "https://fxmacrodata.com/api/v1/announcements/usd/wages?api_key=YOUR_API_KEY&start=2024-01-01"

{
  "data": [
    { "date": "2025-03-14", "val": 4.0, "announcement_datetime": "2025-03-14T12:30:00Z" },
    { "date": "2025-02-07", "val": 4.1, "announcement_datetime": "2025-02-07T13:30:00Z" },
    { "date": "2025-01-10", "val": 3.9, "announcement_datetime": "2025-01-10T13:30:00Z" }
  ]
}

Struktur amplop yang sama berlaku untuk kalender dan forex endpoint, sehingga mudah untuk menulis decoder generik tunggal dan khusus per-endpoint tipe di atasnya.

Langkah 2 Inisialisasi Modul Anda

Buat direktori baru untuk proyek dan inisialisasi modul Go:

mkdir fxmd-go && cd fxmd-go
go mod init fxmd

Anda dapat mengekspornya untuk sesi shell saat ini:

export FXMD_API_KEY="your_actual_api_key_here"

Tip keamanan

Jangan pernah hard-code kunci API dalam file sumber atau berkomitmen untuk kontrol versi. Dalam produksi menggunakan pengelola rahasia atau variabel lingkungan CI / CD. Pola yang ditunjukkan di sini membaca kunci pada saat startup dan gagal dengan cepat jika variabel hilang.

Langkah 3 Tentukan Jenis Tanggapan

Buat file bernama fxmd.go. Mulai dengan mendefinisikan Go struktur yang peta ke bentuk JSON dikembalikan oleh tiga keluarga titik akhir yang akan Anda gunakan:

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"time"
)

const baseURL = "https://fxmacrodata.com/api/v1"

// DataPoint represents a single indicator observation.
type DataPoint struct {
	Date                string  `json:"date"`
	Val                 float64 `json:"val"`
	AnnouncementDatetime string  `json:"announcement_datetime,omitempty"`
}

// AnnouncementsResponse is the envelope for indicator announcement endpoints.
type AnnouncementsResponse struct {
	Data []DataPoint `json:"data"`
}

// CalendarEvent represents one upcoming or recent release on the calendar.
type CalendarEvent struct {
	Date      string  `json:"date"`
	Indicator string  `json:"indicator"`
	Expected  float64 `json:"expected,omitempty"`
	Prior     float64 `json:"prior,omitempty"`
	Actual    float64 `json:"actual,omitempty"`
}

// CalendarResponse is the envelope for the release calendar endpoint.
type CalendarResponse struct {
	Data []CalendarEvent `json:"data"`
}

// ForexPoint represents a single FX spot-rate observation.
type ForexPoint struct {
	Date string  `json:"date"`
	Rate float64 `json:"rate"`
}

// ForexResponse is the envelope for the FX spot-rate endpoint.
type ForexResponse struct {
	Data []ForexPoint `json:"data"`
}

Langkah 4 Membangun klien yang dapat digunakan kembali

Sebuah bungkus tipis di sekitarnya. net/http klien membaca kunci API sekali pada konstruksi, menyuntikkannya sebagai parameter kueri pada setiap permintaan, dan memberlakukan timeout sehingga aliran atas yang lambat tidak pernah dapat menghentikan program Anda tanpa batas waktu:

// Client is a lightweight FXMacroData API client.
type Client struct {
	apiKey     string
	httpClient *http.Client
}

// NewClient creates a Client that reads the API key from the FXMD_API_KEY environment variable.
// It panics at startup if the variable is not set — fail-fast is safer than silent empty results.
func NewClient() *Client {
	key := os.Getenv("FXMD_API_KEY")
	if key == "" {
		panic("FXMD_API_KEY environment variable is not set")
	}
	return &Client{
		apiKey: key,
		httpClient: &http.Client{
			Timeout: 15 * time.Second,
		},
	}
}

// get performs a GET request to the given path with optional query parameters.
// It decodes the JSON body into dest.
func (c *Client) get(path string, params url.Values, dest any) error {
	if params == nil {
		params = url.Values{}
	}
	params.Set("api_key", c.apiKey)

	u := baseURL + path + "?" + params.Encode()
	resp, err := c.httpClient.Get(u)
	if err != nil {
		return fmt.Errorf("http get %s: %w", path, err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return fmt.Errorf("api error %d on %s: %s", resp.StatusCode, path, body)
	}

	if err := json.NewDecoder(resp.Body).Decode(dest); err != nil {
		return fmt.Errorf("json decode %s: %w", path, err)
	}
	return nil
}

Menggunakan json.NewDecoder pada respon tubuh (bukan membaca tubuh ke dalam byte slice pertama) adalah pendekatan idiomatis di Go: ia mengalirkan dekoding langsung dari koneksi HTTP, menghindari alokasi perantara untuk muatan besar.

Langkah 5 Tambahkan pembantu yang ditempelkan untuk setiap keluarga titik akhir

Bungkus generik get metode dengan penolong yang diketik sehingga pemanggil tidak perlu membangun jalur atau mendekode amplop secara manual:

// GetAnnouncements retrieves indicator announcement data for the given currency and indicator slug.
// start and end are optional date strings in "YYYY-MM-DD" format; pass "" to omit them.
//
// Example: client.GetAnnouncements("usd", "wages", "2024-01-01", "")
// Full indicator catalogue: https://fxmacrodata.com/api-data-docs/usd/wages
func (c *Client) GetAnnouncements(currency, indicator, start, end string) (*AnnouncementsResponse, error) {
	params := url.Values{}
	if start != "" {
		params.Set("start", start)
	}
	if end != "" {
		params.Set("end", end)
	}
	var out AnnouncementsResponse
	err := c.get("/announcements/"+currency+"/"+indicator, params, &out)
	return &out, err
}

// GetCalendar retrieves the upcoming release calendar for the given currency code.
//
// Example: client.GetCalendar("usd")
func (c *Client) GetCalendar(currency string) (*CalendarResponse, error) {
	var out CalendarResponse
	err := c.get("/calendar/"+currency, nil, &out)
	return &out, err
}

// GetForex retrieves FX spot-rate history for a currency pair.
// start and end are optional date strings in "YYYY-MM-DD" format.
//
// Example: client.GetForex("eur", "usd", "2024-01-01", "")
func (c *Client) GetForex(base, quote, start, end string) (*ForexResponse, error) {
	params := url.Values{}
	if start != "" {
		params.Set("start", start)
	}
	if end != "" {
		params.Set("end", end)
	}
	var out ForexResponse
	err := c.get("/forex/"+base+"/"+quote, params, &out)
	return &out, err
}

Langkah 6 Sambungkan semuanya `main`

Dengan klien dan pembantu di tempat, memanggil API adalah ringkas dan tipe-aman. main fungsi untuk fxmd.go yang menggunakan ketiga keluarga titik akhir:

func main() {
	client := NewClient()

	// --- Announcements: US wages ---
	fmt.Println("=== US Wages (last 5 releases) ===")
	wages, err := client.GetAnnouncements("usd", "wages", "2024-01-01", "")
	if err != nil {
		fmt.Println("error:", err)
	} else {
		for i, pt := range wages.Data {
			if i >= 5 {
				break
			}
			fmt.Printf("  %s  val=%.2f  released=%s\n", pt.Date, pt.Val, pt.AnnouncementDatetime)
		}
	}

	// --- Release calendar: upcoming USD events ---
	fmt.Println("\n=== Upcoming USD Releases ===")
	cal, err := client.GetCalendar("usd")
	if err != nil {
		fmt.Println("error:", err)
	} else {
		for i, ev := range cal.Data {
			if i >= 5 {
				break
			}
			fmt.Printf("  %s  %s  prior=%.2f  expected=%.2f\n",
				ev.Date, ev.Indicator, ev.Prior, ev.Expected)
		}
	}

	// --- FX spot rates: EUR/USD ---
	fmt.Println("\n=== EUR/USD Spot Rate (last 5 days) ===")
	fx, err := client.GetForex("eur", "usd", "2025-01-01", "")
	if err != nil {
		fmt.Println("error:", err)
	} else {
		for i, pt := range fx.Data {
			if i >= 5 {
				break
			}
			fmt.Printf("  %s  rate=%.5f\n", pt.Date, pt.Rate)
		}
	}
}

Jalankan program:

go run fxmd.go

Anda harus melihat output yang mirip dengan:

=== US Wages (last 5 releases) ===
  2025-03-14  val=4.00  released=2025-03-14T12:30:00Z
  2025-02-07  val=4.10  released=2025-02-07T13:30:00Z
  2025-01-10  val=3.90  released=2025-01-10T13:30:00Z
  2024-12-06  val=4.00  released=2024-12-06T13:30:00Z
  2024-11-01  val=4.00  released=2024-11-01T12:30:00Z

=== Upcoming USD Releases ===
  2025-04-25  gdp  prior=2.30  expected=0.40
  2025-05-02  non_farm_payrolls  prior=228.00  expected=135.00
  2025-05-13  inflation  prior=2.40  expected=2.30

=== EUR/USD Spot Rate (last 5 days) ===
  2025-04-17  rate=1.13452
  2025-04-16  rate=1.13680
  2025-04-15  rate=1.13590
  2025-04-14  rate=1.13320
  2025-04-11  rate=1.13580

Tips Mengambil secara bersamaan dengan rutinitas

Karena klien aman untuk penggunaan bersamaan, Anda dapat menyebarkan beberapa permintaan indikator secara paralel menggunakan goroutines dan sync.WaitGroup atau errgroup. Ini sangat berguna ketika membangun dasbor yang menarik beberapa mata uang sekaligus waktu jam dinding tetap dekat dengan latensi permintaan tunggal paling lambat daripada jumlah semua permintaan.

Langkah 7 Mengatasi Paginasi dan Jangkauan Tanggal

Secara default, announcements endpoint mengembalikan semua riwayat yang tersedia. Pasokan uang M2 atau PDB Anda akan sering ingin membatasi jendela menggunakan start Dan end kedua helper sudah mendukung mereka. Berikut adalah contoh yang fokus yang mengambil hanya kuartal terbaru dari Pekerjaan paruh waktu AS data:

// Fetch US part-time employment for the last 90 days
end := time.Now().Format("2006-01-02")
start := time.Now().AddDate(0, 0, -90).Format("2006-01-02")

pt, err := client.GetAnnouncements("usd", "part_time_employment", start, end)
if err != nil {
    log.Fatal(err)
}
for _, dp := range pt.Data {
    fmt.Printf("%s  %.0f\n", dp.Date, dp.Val)
}

Go standar time format paket tanggal sebagai "2006-01-02" (waktu referensi adalah mnemonik: 01/02 03:04:05 PM '06 -0700), yang cocok dengan string tanggal ISO-8601 yang diharapkan oleh API.

Langkah 8 Parse `announcement_datetime` sebagai `time.Time`

- Apa? announcement_datetime field adalah string UTC RFC-3339. Jika aplikasi Anda perlu menghitung waktu untuk rilis countdowns, mengurutkan peristiwa, atau ember data oleh sesi, menganalisis ke dalam time.Time nilai:

const rfc3339 = time.RFC3339

for _, dp := range wages.Data {
    if dp.AnnouncementDatetime == "" {
        continue
    }
    t, err := time.Parse(rfc3339, dp.AnnouncementDatetime)
    if err != nil {
        log.Printf("bad datetime %q: %v", dp.AnnouncementDatetime, err)
        continue
    }
    until := time.Until(t)
    fmt.Printf("%s  val=%.2f  in %s\n", dp.Date, dp.Val, until.Round(time.Minute))
}

Daftar File Lengkap

Untuk referensi, berikut adalah implementasi file tunggal lengkap yang dijelaskan dalam langkah-langkah di atas:

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"time"
)

const baseURL = "https://fxmacrodata.com/api/v1"

type DataPoint struct {
	Date                string  `json:"date"`
	Val                 float64 `json:"val"`
	AnnouncementDatetime string  `json:"announcement_datetime,omitempty"`
}

type AnnouncementsResponse struct {
	Data []DataPoint `json:"data"`
}

type CalendarEvent struct {
	Date      string  `json:"date"`
	Indicator string  `json:"indicator"`
	Expected  float64 `json:"expected,omitempty"`
	Prior     float64 `json:"prior,omitempty"`
	Actual    float64 `json:"actual,omitempty"`
}

type CalendarResponse struct {
	Data []CalendarEvent `json:"data"`
}

type ForexPoint struct {
	Date string  `json:"date"`
	Rate float64 `json:"rate"`
}

type ForexResponse struct {
	Data []ForexPoint `json:"data"`
}

type Client struct {
	apiKey     string
	httpClient *http.Client
}

func NewClient() *Client {
	key := os.Getenv("FXMD_API_KEY")
	if key == "" {
		panic("FXMD_API_KEY environment variable is not set")
	}
	return &Client{
		apiKey: key,
		httpClient: &http.Client{Timeout: 15 * time.Second},
	}
}

func (c *Client) get(path string, params url.Values, dest any) error {
	if params == nil {
		params = url.Values{}
	}
	params.Set("api_key", c.apiKey)
	u := baseURL + path + "?" + params.Encode()
	resp, err := c.httpClient.Get(u)
	if err != nil {
		return fmt.Errorf("http get %s: %w", path, err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return fmt.Errorf("api error %d on %s: %s", resp.StatusCode, path, body)
	}
	return json.NewDecoder(resp.Body).Decode(dest)
}

func (c *Client) GetAnnouncements(currency, indicator, start, end string) (*AnnouncementsResponse, error) {
	params := url.Values{}
	if start != "" { params.Set("start", start) }
	if end != ""   { params.Set("end",   end)   }
	var out AnnouncementsResponse
	return &out, c.get("/announcements/"+currency+"/"+indicator, params, &out)
}

func (c *Client) GetCalendar(currency string) (*CalendarResponse, error) {
	var out CalendarResponse
	return &out, c.get("/calendar/"+currency, nil, &out)
}

func (c *Client) GetForex(base, quote, start, end string) (*ForexResponse, error) {
	params := url.Values{}
	if start != "" { params.Set("start", start) }
	if end != ""   { params.Set("end",   end)   }
	var out ForexResponse
	return &out, c.get("/forex/"+base+"/"+quote, params, &out)
}

func main() {
	client := NewClient()

	wages, err := client.GetAnnouncements("usd", "wages", "2024-01-01", "")
	if err != nil {
		fmt.Println("wages error:", err)
	} else {
		fmt.Println("=== US Wages ===")
		for i, pt := range wages.Data {
			if i >= 5 { break }
			fmt.Printf("  %s  %.2f\n", pt.Date, pt.Val)
		}
	}

	cal, err := client.GetCalendar("usd")
	if err != nil {
		fmt.Println("calendar error:", err)
	} else {
		fmt.Println("=== Upcoming USD Releases ===")
		for i, ev := range cal.Data {
			if i >= 5 { break }
			fmt.Printf("  %s  %s\n", ev.Date, ev.Indicator)
		}
	}

	fx, err := client.GetForex("eur", "usd", "2025-01-01", "")
	if err != nil {
		fmt.Println("forex error:", err)
	} else {
		fmt.Println("=== EUR/USD ===")
		for i, pt := range fx.Data {
			if i >= 5 { break }
			fmt.Printf("  %s  %.5f\n", pt.Date, pt.Rate)
		}
	}
}

Apa yang Selanjutnya?

Anda sekarang memiliki klien Go yang bekerja yang mencakup tiga keluarga endpoint FXMacroData yang paling umum.

Memperluas definisi struktur untuk menangkap bidang tambahan seperti revised nilai dari titik akhir kalender.
Tambahkan errgroup-berbasis kipas untuk mengambil beberapa mata uang secara bersamaan the Client aman untuk dibagikan di seluruh goroutines karena http.Client adalah aman simultan oleh desain.
Hasil persisten ke database SQLite lokal menggunakan database/sql untuk backtesting ringan atau penelitian sinyal.
Jelajahi katalog indikator lengkap untuk USD pada /api-data-docs/usd/gaji dan untuk mata uang lain di seluruh dasbor cari M2Aku akan pergi. pekerjaan paruh waktu, dan PDB sebagai titik awal mengingat sinyal permintaan yang memotivasi panduan ini.

How To Use The Fxmacrodata Api With Go

Persyaratan

Langkah 1 Memahami Bentuk API

Langkah 2 Inisialisasi Modul Anda

Langkah 3 Tentukan Jenis Tanggapan

Langkah 4 Membangun klien yang dapat digunakan kembali

Langkah 5 Tambahkan pembantu yang ditempelkan untuk setiap keluarga titik akhir

Langkah 6 Sambungkan semuanya `main`

Langkah 7 Mengatasi Paginasi dan Jangkauan Tanggal

Langkah 8 Parse `announcement_datetime` sebagai `time.Time`

Daftar File Lengkap

Apa yang Selanjutnya?

More Articles

Blogroll

Key Facts

Quick Q&A

Persyaratan

Langkah 1 Memahami Bentuk API

Langkah 2 Inisialisasi Modul Anda

Langkah 3 Tentukan Jenis Tanggapan

Langkah 4 Membangun klien yang dapat digunakan kembali

Langkah 5 Tambahkan pembantu yang ditempelkan untuk setiap keluarga titik akhir

Langkah 6 Sambungkan semuanya main

Langkah 7 Mengatasi Paginasi dan Jangkauan Tanggal

Langkah 8 Parse announcement_datetime sebagai time.Time

Daftar File Lengkap

Apa yang Selanjutnya?

More Articles

Blogroll

Key Facts

Quick Q&A

Langkah 6 Sambungkan semuanya `main`

Langkah 8 Parse `announcement_datetime` sebagai `time.Time`