factual

README

factual-go-driver

Get using OAuth

import (
  "net/url"

  "github.com/ainsleyc/factual"
  "github.com/bitly/go-simplejson"
)

// Initialization
key := "Factual API key"
secret := "Factual API secret"
client := factual.NewClient(key, secret)

// Get request
path := "/t/places-us"
params := url.Values{}
params.Set("q": "starbucks")
resp, err := client.Get(path, params)

// Parse response
respJson, err := simplejson.NewJson(resp)
data := respJson.Get("response").Get("data")

Get using "KEY" parameter

path := "/geotag"
params := url.Values{}
params.Set("latitude", "37.782137")
params.Set("longitude", "-122.405803")

// Setting "KEY" parameter converts request to non-oauth
params.Set("KEY", "Factual API key")

resp, err := client.Get(path, params)

Comparison Filters

params := url.Values{}
filters, err := factual.NewComparisonFilter(
  "name",
  factual.Eq,
  "starbucks",
).MarshalJSON()
params.Set("filters", string(filters))

Logical Filters

params := url.Values{}
filter1 := factual.NewComparisonFilter(
  "name",
  factual.Eq,
  "starbucks",
)
filter2 := factual.NewComparisonFilter(
  "locality",
  factual.Eq,
  "new york",
)
andFilter, err := factual.NewLogicalFilter(
  factual.And,
  []factual.Filter{filter1, filter2},
).MarshalJSON()
params.Set("filters", string(andFilter))

Geo Circle Filters

params := url.Values{}
geo, err := factual.NewGeoCircle(
  float64(34.06021),   // Latitude
  float64(-118.41828), // Longitude
  50,                  // Radius (m)
).MarshalJSON()
params.Set("geo", string(geo))

Geo Rectangle Filters

params := url.Values{}
geo, err := factual.NewGeoRect(
  float64(34.06110),   // Upper left corner latitude
  float64(-118.42283), // Upper left corner longitude
  float64(34.05771),   // Bottom right corner latitude
  float64(-118.41399), // Bottom right corner longitude
).MarshalJSON()
params.Set("geo", string(geo))

package main

import (
	"encoding/json"
	"log"
	"net/http"
	"net/url"
)

func main() {
	http.HandleFunc("/auto", auto)
	log.Fatal(http.ListenAndServe(":12345", nil))
}

func auto(w http.ResponseWriter, r *http.Request) {

	path := "/t/places-us"
	params := url.Values{}
	q := "ba"

	cmpFilter := driver.NewComparisonFilter(
		"name",
		driver.Bw,
		q,
	)

	bs, err := json.Marshal(cmpFilter)
	if err != nil {
		return httputils.NewServerErr(err)
	}

	params.Set("filters", string(bs))

	wc := driver.WithRequest(r)
	client := driver.NewClient(key, secret, wc)

	bs, err = client.Get(path, params)
	if err != nil {
		return httputils.NewServerErr(err)
	}

	w.Write(bs)
	w.WriteHeader(200)
}

Documentation

Index

• func ErrHttpBody(url string) error
• func ErrHttpResponse(url string, code int, resp []byte) error
• func ErrInvalidUrl(url string) error
• type Client
  • func NewClient(key string, secret string, opts ...Option) Client
  • func (c Client) Get(path string, params url.Values) ([]byte, error)
• type ComparisonFilter
  • func NewComparisonFilter(field string, op ComparisonOperator, vals interface{}) *ComparisonFilter
  • func (f *ComparisonFilter) MarshalJSON() ([]byte, error)
• type ComparisonOperator
• type Filter
• type Geo
• type GeoCircle
  • func NewGeoCircle(lat float64, long float64, radius int) *GeoCircle
  • func (g *GeoCircle) MarshalJSON() ([]byte, error)
• type GeoOperator
• type GeoRect
  • func NewGeoRect(tlLat float64, tlLong float64, brLat float64, brLong float64) *GeoRect
  • func (g *GeoRect) MarshalJSON() ([]byte, error)
• type Hours
• type LogicalFilter
  • func NewLogicalFilter(op LogicalOperator, vals []Filter) *LogicalFilter
  • func (f *LogicalFilter) MarshalJSON() ([]byte, error)
• type LogicalOperator
• type Option
• type Place
• type PlaceResponse
• type PlaceWrap

Functions

func ErrHttpBody

func ErrHttpBody(url string) error

func ErrHttpResponse

func ErrHttpResponse(url string, code int, resp []byte) error

func ErrInvalidUrl

func ErrInvalidUrl(url string) error

Types

type Client

type Client struct {
	Oauth   oauth.Client
	BaseUri string
	// contains filtered or unexported fields
}

func NewClient

func NewClient(key string, secret string, opts ...Option) Client

NewClient accepts a client ID and client secret and returns a factual client. It accepts variable number of functional options for configuring the client.

func (Client) Get

func (c Client) Get(path string, params url.Values) ([]byte, error)

type ComparisonFilter

type ComparisonFilter struct {
	Field string
	Op    ComparisonOperator
	Vals  interface{}
}

func NewComparisonFilter

func NewComparisonFilter(field string, op ComparisonOperator, vals interface{}) *ComparisonFilter

func (*ComparisonFilter) MarshalJSON

func (f *ComparisonFilter) MarshalJSON() ([]byte, error)

type ComparisonOperator

type ComparisonOperator string

const (
	Blank       ComparisonOperator = "$blank"
	Bw          ComparisonOperator = "$bw"
	Bwin        ComparisonOperator = "$bwin"
	Eq          ComparisonOperator = "$eq"
	Excludes    ComparisonOperator = "$excludes"
	ExcludesAny ComparisonOperator = "$excludes_any"
	Gt          ComparisonOperator = "$gt"
	Gte         ComparisonOperator = "$gte"
	Includes    ComparisonOperator = "$includes"
	IncludesAny ComparisonOperator = "$includes_any"
	Lt          ComparisonOperator = "$lt"
	Lte         ComparisonOperator = "$lte"
	Nbw         ComparisonOperator = "$nbw"
	Nbwin       ComparisonOperator = "$bnwin"
	Neq         ComparisonOperator = "$neq"
	Nin         ComparisonOperator = "$nin"
	Search      ComparisonOperator = "$search"
)

type Filter

type Filter interface {
	MarshalJSON() ([]byte, error)
	// contains filtered or unexported methods
}

type Geo

type Geo interface {
	MarshalJSON() ([]byte, error)
	// contains filtered or unexported methods
}

type GeoCircle

type GeoCircle struct {
	// contains filtered or unexported fields
}

func NewGeoCircle

func NewGeoCircle(lat float64, long float64, radius int) *GeoCircle

func (*GeoCircle) MarshalJSON

func (g *GeoCircle) MarshalJSON() ([]byte, error)

type GeoOperator

type GeoOperator string

const (
	Circle GeoOperator = "$circle"
	Rect   GeoOperator = "$rect"
	Center GeoOperator = "$center"
	Within GeoOperator = "$within"
	Meters GeoOperator = "$meters"
)

type GeoRect

type GeoRect struct {
	TlLat  float64
	TlLong float64
	BrLat  float64
	BrLong float64
}

func NewGeoRect

func NewGeoRect(tlLat float64, tlLong float64,
	brLat float64, brLong float64) *GeoRect

func (*GeoRect) MarshalJSON

func (g *GeoRect) MarshalJSON() ([]byte, error)

type Hours

type Hours struct {
	Monday    [][]string `json:"monday"`
	Tuesday   [][]string `json:"tuesday"`
	Wednesday [][]string `json:"wednesday"`
	Thursday  [][]string `json:"thursday"`
	Friday    [][]string `json:"friday"`
	Saturday  [][]string `json:"saturday"`
	Sunday    [][]string `json:"sunday"`
}

Hours describes the open hours for a place

type LogicalFilter

type LogicalFilter struct {
	Op   LogicalOperator
	Vals []Filter
}

func NewLogicalFilter

func NewLogicalFilter(op LogicalOperator, vals []Filter) *LogicalFilter

func (*LogicalFilter) MarshalJSON

func (f *LogicalFilter) MarshalJSON() ([]byte, error)

type LogicalOperator

type LogicalOperator string

const (
	And LogicalOperator = "$and"
	Or  LogicalOperator = "$or"
)

type Option

type Option func(c *Client) error

Option are functional options for configuring a Client

type Place

type Place struct {
	FactualID      string     `json:"factual_id"`
	CategoryIDs    []int      `json:"category_ids"`
	CategoryLabels [][]string `json:"category_labels"`
	ChainID        string     `json:"chain_id,omitempty"`
	ChainName      string     `json:"chain_name,omitempty"`

	Address  string `json:"address"`
	Country  string `json:"country"`
	Postcode string `json:"postcode"`
	Fax      string `json:"fac"`
	Region   string `json:"region"`
	Tel      string `json:"tel"`

	Hours        Hours    `json:"hours"`
	HoursDisplay string   `json:"hours_display"`
	Latitude     float64  `json:"latitude"`
	Longitude    float64  `json:"latitude"`
	Locality     string   `json:"locality"`
	Name         string   `json:"name"`
	Neighborhood []string `json:"neighborhood"`
	Website      string   `json:"website"`
}

Place contains the properties of a Place

type PlaceResponse

type PlaceResponse struct {
	Data         []Place `json:"data"`
	IncludedRows int     `json:"included_rows"`
}

PlaceResponse is schema returned by the Factual API

type PlaceWrap

type PlaceWrap struct {
	Version  int           `json:"version"`
	Status   string        `json:"status"`
	Response PlaceResponse `json:"response"`
}

PlaceWrap allows unmarshalling of API response metadata