kenall

README

go-kenall

About

Unofficially kenall (ケンオール) client written by Go.

Install

$ go get github.com/osamingo/go-kenall@v1.2.0

Usage

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/osamingo/go-kenall"
)

func main() {
	cli, err := kenall.NewClient(os.Getenv("KENALL_AUTHORIZATION_TOKEN"))
	if err != nil {
		log.Fatal(err)
	}

	resAddr, err := cli.GetAddress(context.Background(), "1000001")
	if err != nil {
		log.Fatal(err)
	}
	addr := resAddr.Addresses[0]
	fmt.Println(addr.Prefecture, addr.City, addr.Town)
	// Output: 東京都 千代田区 千代田

	resCity, err := cli.GetCity(context.Background(), "13")
	if err != nil {
		log.Fatal(err)
	}
	city := resCity.Cities[0]
	fmt.Println(city.Prefecture, city.City)
	// Output: 東京都 千代田区
}

Articles

• ケンオール通信第1号
  • This library has been featured on the official blog 🎉

License

Released under the MIT License.

Documentation

Index

• Constants
• Variables
• type Address
• type City
• type Client
  • func NewClient(token string, opts ...ClientOption) (*Client, error)
  • func (cli *Client) GetAddress(ctx context.Context, postalCode string) (*GetAddressResponse, error)
  • func (cli *Client) GetCity(ctx context.Context, prefectureCode string) (*GetCityResponse, error)
• type ClientOption
  • func WithEndpoint(endpoint string) ClientOption
  • func WithHTTPClient(cli *http.Client) ClientOption
• type GetAddressResponse
• type GetCityResponse
• type Version
  • func (v *Version) UnmarshalJSON(data []byte) error

Examples

• Client.GetAddress
• Client.GetCity

Constants

const (
	// Endpoint is an endpoint provided by the kenall service.
	Endpoint = "https://api.kenall.jp/v1"
	// RFC3339DateFormat is the RFC3339-Date format for Go.
	RFC3339DateFormat = "2006-01-02"
)

Variables

var (
	// ErrInvalidArgument is an error value that will be returned if the value of the argument is invalid.
	ErrInvalidArgument = fmt.Errorf("kenall: invalid argument")
	// ErrUnauthorized is an error value that will be returned if the authorization token is invalid.
	ErrUnauthorized = fmt.Errorf("kenall: 401 unauthorized error")
	// ErrPaymentRequired is an error value that will be returned if the payment for your kenall account is overdue.
	ErrPaymentRequired = fmt.Errorf("kenall: 402 payment required error")
	// ErrForbidden is an error value that will be returned when the resource does not have access privileges.
	ErrForbidden = fmt.Errorf("kenall: 403 forbidden error")
	// ErrNotFound is an error value that will be returned when there is no resource to be retrieved.
	ErrNotFound = fmt.Errorf("kenall: 404 not found error")
	// ErrMethodNotAllowed is an error value that will be returned when the request calls a method that is not allowed.
	ErrMethodNotAllowed = fmt.Errorf("kenall: 405 method not allowed error")
	// ErrInternalServerError is an error value that will be returned when some error occurs in the kenall service.
	ErrInternalServerError = fmt.Errorf("kenall: 500 internal server error")
	// ErrTimeout is an error value that will be returned when the request is timeout.
	ErrTimeout = func(err error) error { return fmt.Errorf("kenall: request timeout: %w", err) }
)

Types

type Address

type Address struct {
	JISX0402           string `json:"jisx0402"`
	OldCode            string `json:"old_code"`
	PostalCode         string `json:"postal_code"`
	PrefectureKana     string `json:"prefecture_kana"`
	CityKana           string `json:"city_kana"`
	TownKana           string `json:"town_kana"`
	TownKanaRaw        string `json:"town_kana_raw"`
	Prefecture         string `json:"prefecture"`
	City               string `json:"city"`
	Town               string `json:"town"`
	Koaza              string `json:"koaza"`
	KyotoStreet        string `json:"kyoto_street"`
	Building           string `json:"building"`
	Floor              string `json:"floor"`
	TownPartial        bool   `json:"town_partial"`
	TownAddressedKoaza bool   `json:"town_addressed_koaza"`
	TownChome          bool   `json:"town_chome"`
	TownMulti          bool   `json:"town_multi"`
	TownRaw            string `json:"town_raw"`
	Corporation        struct {
		Name        string `json:"name"`
		NameKana    string `json:"name_kana"`
		BlockLot    string `json:"block_lot"`
		BlockLotNum string `json:"block_lot_num"`
		PostOffice  string `json:"post_office"`
		CodeType    int    `json:"code_type"`
	} `json:"corporation"`
}

An Address is an address associated with the postal code defined by JP POST.

type City

type City struct {
	JISX0402       string `json:"jisx0402"`
	PrefectureCode string `json:"prefecture_code"`
	CityCode       string `json:"city_code"`
	PrefectureKana string `json:"prefecture_kana"`
	CityKana       string `json:"city_kana"`
	Prefecture     string `json:"prefecture"`
	City           string `json:"city"`
}

A City is a city associated with the prefecture code defined by JIS X 0401.

type Client

type Client struct {
	HTTPClient *http.Client
	Endpoint   string
	// contains filtered or unexported fields
}

A Client implements API requests to the kenall service.

func NewClient

func NewClient(token string, opts ...ClientOption) (*Client, error)

NewClient creates kenall.Client with the authorization token provided by the kenall service.

func (*Client) GetAddress

func (cli *Client) GetAddress(ctx context.Context, postalCode string) (*GetAddressResponse, error)

GetAddress requests to the kenall service to get the address by postal code.

Example

if testing.Short() {
	// stab
	fmt.Print("false\n東京都 千代田区 千代田\n")

	return
}

// NOTE: Please set a valid token in the environment variable and run it.
cli, err := kenall.NewClient(os.Getenv("KENALL_AUTHORIZATION_TOKEN"))
if err != nil {
	log.Fatal(err)
}

res, err := cli.GetAddress(context.Background(), "1000001")
if err != nil {
	log.Fatal(err)
}

addr := res.Addresses[0]
fmt.Println(time.Time(res.Version).IsZero())
fmt.Println(addr.Prefecture, addr.City, addr.Town)

Output:

false
東京都 千代田区 千代田

func (*Client) GetCity

func (cli *Client) GetCity(ctx context.Context, prefectureCode string) (*GetCityResponse, error)

GetCity requests to the kenall service to get the city by prefecture code.

Example

if testing.Short() {
	// stab
	fmt.Print("false\n東京都 千代田区\n")

	return
}

// NOTE: Please set a valid token in the environment variable and run it.
cli, err := kenall.NewClient(os.Getenv("KENALL_AUTHORIZATION_TOKEN"))
if err != nil {
	log.Fatal(err)
}

res, err := cli.GetCity(context.Background(), "13")
if err != nil {
	log.Fatal(err)
}

addr := res.Cities[0]
fmt.Println(time.Time(res.Version).IsZero())
fmt.Println(addr.Prefecture, addr.City)

Output:

false
東京都 千代田区

type ClientOption

type ClientOption interface {
	Apply(*Client)
}

A ClientOption provides a customize option for kenall.Client.

func WithEndpoint

func WithEndpoint(endpoint string) ClientOption

WithEndpoint injects optional endpoint to kenall.Client.

func WithHTTPClient

func WithHTTPClient(cli *http.Client) ClientOption

WithHTTPClient injects optional HTTP Client to kenall.Client.

type GetAddressResponse

type GetAddressResponse struct {
	Version   Version    `json:"version"`
	Addresses []*Address `json:"data"`
}

A GetAddressResponse is a result from the kenall service of the API to get the address from the postal code.

type GetCityResponse

type GetCityResponse struct {
	Version Version `json:"version"`
	Cities  []*City `json:"data"`
}

A GetCityResponse is a result from the kenall service of the API to get the city from the prefecture code.

type Version

type Version time.Time

A Version is the version-controlled date of the retrieved data.

func (*Version) UnmarshalJSON

func (v *Version) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.