Documentation ¶
Index ¶
- Constants
- func APIError(e error) *tError
- func Init(params ...interface{}) error
- func ParamDisableFirstMeCall() tClientParam
- func ParamFields(fields ...string) tClientParam
- func ParamToken(token string) tClientParam
- func ParamUseHTTPS(is bool) tClientParam
- func R() *tRequest
- type Client
- type Response
Constants ¶
const ( // Returns the requested IP address. FieldIp string = "ip" // Returns the hostname the requested IP resolves to, // only returned if Hostname Lookup is enabled. FieldHostname string = "hostname" // Returns the IP address type IPv4 or IPv6. FieldType string = "type" // Returns the 2-letter continent code associated with the IP. FieldContinentCode string = "continent_code" // Returns the name of the continent associated with the IP. FieldContinentName string = "continent_name" // Returns the 2-letter country code associated with the IP. FieldCountryCode string = "country_code" // Returns the name of the country associated with the IP. FieldCountryName string = "country_name" // Returns the region code of the region associated with the IP // (e.g. CA for California). FieldRegionCode string = "region_code" // Returns the name of the region associated with the IP. FieldRegionName string = "region_name" // Returns the name of the city associated with the IP. FieldCity string = "city" // Returns the ZIP code associated with the IP. FieldZip string = "zip" // Returns the latitude value associated with the IP. FieldLatitude string = "latitude" // Returns the longitude value associated with the IP. FieldLongitude string = "longitude" // Returns multiple location-related objects FieldLocation string = "location" // Returns the unique geoname identifier // in accordance with the Geonames Registry.z FieldLocationGeonameId string = "location.geoname_id" // Returns the capital city of the country associated with the IP. FieldLocationCapital string = "location.capital" // Returns an object containing one or multiple // sub-objects per language spoken in the country associated with the IP. FieldLocationLanguages string = "location.languages" // Returns the 2-letter language code for the given language. FieldLocationLanguagesCode string = "location.languages.code" // Returns the name (in the API request's main language) // of the given language. (e.g. Portuguese) FieldLocationLanguagesName string = "location.languages.name" // Returns the native name of the given language. (e.g. Português) FieldLocationLanguagesNative string = "location.languages.native" // Returns an HTTP URL leading to an SVG-flag icon for the country // associated with the IP. FieldLocationCountryFlag string = "location.country_flag" // Returns the emoji icon for the flag of the country associated with the IP. FieldLocationCountryFlagEmoji string = "location.country_flag_emoji" // Returns the unicode value of the emoji icon for the flag of the country // associated with the IP. (e.g. U+1F1F5 U+1F1F9 for the Portuguese flag) FieldLocationCountryFlagEmojiUnicode string = "location.country_flag_emoji_unicode" // Returns the calling/dial code of the country associated with the IP. // (e.g. 351) for Portugal. FieldLocationCallingCode string = "location.calling_code" // Returns true or false depending on whether or not the county // associated with the IP is in the European Union. FieldLocationIsEu string = "location.is_eu" // Returns an object containing timezone-related data. FieldTimeZone string = "timezone" // Returns the ID of the time zone associated with the IP. // (e.g. America/LosAngeles for PST) FieldTimeZoneId string = "timezone.id" // Returns the current date and time in the location // associated with the IP. (e.g. 2018-03-29T22:31:27-07:00) FieldTimeZoneCurrentTime string = "timezone.current_time" // Returns the GMT offset of the given time zone in seconds. // (e.g. -25200 for PST's -7h GMT offset) FieldTimeZoneGmtOffset string = "timezone.gmt_offset" // Returns the universal code of the given time zone. FieldTimeZoneCode string = "timezone.code" // Returns true or false depending on whether or not the given time zone // is considered daylight saving time. FieldTimeZoneIsDaylightSaving string = "timezone.is_daylight_saving" // Returns an object containing currency-related data. FieldCurrency string = "currency" // Returns the 3-letter code of the main currency associated with the IP. FieldCurrencyCode string = "currency.code" // Returns the name of the given currency. FieldCurrencyName string = "currency.mame" // Returns the plural name of the given currency. FieldCurrencyPlural string = "currency.plural" // Returns the symbol letter of the given currency. FieldCurrencySymbol string = "currency.symbol" // Returns the native symbol letter of the given currency. FieldCurrencySymbolNative string = "currency.symbol_native" // Returns an object containing connection-related data. FieldConnection string = "connection" // Returns the Autonomous System Number associated with the IP. FieldConnectionAsn string = "connection.asn" // Returns the name of the ISP associated with the IP. FieldConnectionIsp string = "connection.isp" // Returns an object containing security-related data. FieldSecurity string = "security" // Returns true or false depending on whether or not the given IP // is associated with a proxy. FieldSecurityIsProxy string = "security.is_proxy" // Returns the type of proxy the IP is associated with. FieldSecurityProxyType string = "security.proxy_type" // Returns true or false depending on whether or not the given IP // is associated with a crawler. FieldSecurityIsCrawler string = "security.is_crawler" // Returns the name of the crawler the IP is associated with. FieldSecurityCrawlerName string = "security.crawler_name" // Returns the type of crawler the IP is associated with. FieldSecurityCrawlerType string = "security.crawler_type" // Returns true or false depending on whether or not the given IP // is associated with the anonymous Tor system. FieldSecurityIsTor string = "security.is_tor" // Returns the type of threat level the IP is associated with. FieldSecurityThreatLevel string = "security.threat_level" // Returns an object containing all threat types associated with the IP. FieldSecurityThreatTypes string = "security.threat_types" )
Predefined consts each of that represents some field in JSON response from ipstack on the some request.
So, you can read on https://ipstack.com/documentation that you can specify what fields should be returned as response. Using that consts and 'Fields' method of 'Client' or 'tRequest' classes you can do it.
Variables ¶
This section is empty.
Functions ¶
func APIError ¶
func APIError(e error) *tError
'APIError' tries to cast 'e' object to the 'tError' object. 'tError' is the internal private class, represents the some Web API error. If 'e' is the object of 'tError' class, it will be returned by pointer, otherwise nil is returned.
Because all methods that returns an error object, return object of 'error' interface, not an 'tError' instance, in golang you must check if some object that implements 'error' interface is really 'tError' instance. You can use this function for it and then, for example, if you want to check the error code, just call 'Code' method. Even if this method will return nil as '*tError' object, method 'Code' willn't panic and 0 will be returned by 'Code'. Check methods 'Code', 'Type' and 'Info' for details.
func Init ¶
func Init(params ...interface{}) error
'Init' initializes 'DefaultClient' variable. This variable represents default client that used by package functions 'IP', 'IPs' and 'UpdateMe'.
Thus, you can just once call 'Init' function (initialize default client) and then in any place just call 'IP', 'IPs', 'UpdateMe' package level functions and accessing to the 'DefaultClient' variable. Thus you will have only one 'Client' instance in all your app, and if it's enough for you, you do not need to call 'New' directly for creting other 'Client' object, and most importantly do not need to worry about where to store 'Client' object, or about how to provide access to storing object and other architecture solutions. Just call 'Init' and then call package level functions. It's so easy and simple.
NOTE! You can call this function as much as you want. I can't imagine for what you might need this feature, but it's possible. In that case, the behaviour is predictable - the previous version of default client will be overwritten by new. BUT! If any error occurred while trying to reinitialize default client (create new object of default client) the previous default client willn't be overwritten by nil object and also will be available.
NOTE! See 'New' docs to understand what you must or can pass as arguments.
func ParamDisableFirstMeCall ¶
func ParamDisableFirstMeCall() tClientParam
'ParamDisableFirstMeCall' creates a parameter for 'Client' constructors that skips the first internal calling 'Me' method when 'Client' object will be created successfully.
NOTE! Yes, when you create a 'Client' object by default it tries to perform first test query, and if it was successfull, the 'Client' object treates as succeessfully created (and response object is decoded and stored as info of the current IP address and will be available by calling 'Me' method w/o force fetch).
func ParamFields ¶
func ParamFields(fields ...string) tClientParam
'ParamFields' creates a parameter for 'Client' constructors that allows you to specifiy what kinds of response you want to get from ipstack Web API.
You can pass as many fields as you want. You can write field names manually or using predefined consts started with 'Field...' prefix and described above.
func ParamToken ¶
func ParamToken(token string) tClientParam
'ParamToken' creates a parameter for 'Client' constructors that specifies the API token, 'Client' object must be created with.
func ParamUseHTTPS ¶
func ParamUseHTTPS(is bool) tClientParam
'ParamUseHTTPS' creates a parameter for 'Client' constructors that obliges to always use HTTPS schema instead HTTP.
WARNING! You can use HTTPS schema only if you have non-free ipstack account.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
'Client' is the class that represents golang point to make Web API requests to ipstack.
WARNING! Do not create this object directly! This class has important private fields that must be initialized only by constructor. Use 'New' function to create a new 'Client' object.
After 'Client' object created, (and if you don't disable first check) you already have an information about your IP.
var DefaultClient *Client
Default client. It will be initialized directly by calling 'Init' function, or when you will call 'New' function first time and that call will be successfull, the 'New' function will also tagged the created client as default client (will store pointer to the 'DefaultClient').
func New ¶
'New' creates a new 'Client' instance with specified 'params'. When object created and all required prechecks are completed and passed, constructor tries to perform test request: Checking IP address of machine request made from. If it will be successfull, the result will be saved as 'Me' field in 'Client' object, and current timestamp will be saved as 'MeTimestamp'.
NOTE: If any error will be occur at the some step, the not nil error object will be returned as second return argument.
NOTE: If the second return argument (error object) isn't nil, the first argument ('Client' object by pointer) is nil! Always! No exceptions!
Arguments: You can pass arguments of some different types in the order you want. Arguments will be identified by its type. If you will pass argument of unsupported type, it will be ignored. if you will pass more than one params of the same type, the all previous values will be shadowed by the last value. [*] - means that this argument is required.
-- Table of supported argument's types and how they treated are --
[*] {string, []byte} Token. API token that will be used as accessing token to perform each request to the ipstack Web API. If this argument willn't pass, error will return immediately.
[ ] {http.Client, *http.Client} Golang HTTP client. This object will be used to perform each request to the ipstack Web API. If this argument willn't pass, the HTTP client with default params will be used (see docs for 'http.Client' golang package).
func (*Client) IP ¶
'IP' returns the info about 'ip' as 'Response' object. If any error occur, the second return argument will contain error object.
func (*Client) IPs ¶
'IPs' returns the info about each requested IP addresses (you can pass more than one IP address as arguments) as slice of 'Response' objects. You can pass up to 50 IP addresses to the this method. If any error occur, the second argument will contain error object.
func (*Client) Me ¶
'Me' fetches the fresh info about your IP address and if this operation was successfull, store it as 'Me' field of the current object. todo: fix comment
func (*Client) R ¶
func (c *Client) R() *tRequest
'R' is the way to the improve your flexibility! 'R' returns the 'tRequest' object - object of special type, that contains in itself all important data to perform Web API request, and, that most importantly, have some methods to change its behaviour! See docs for 'tRequest' object and see 'tRequest' methods.
NOTE! Yes, it's very simple. You can just call 'R' method of your client object, or call 'R' package level function to get package level default client request object, then call all methods to configure request sentence and then just call 'IP' or 'IPs' methods and you'll get result you want w/o changes behaviour of your 'Client' object!
For example: c, err := ipstack.New(...) resp, err := c.R().<some_configure_method>(...).IP(1.2.3.4)
And, of course, you can chain all configure methods!
For example: _, _ := c.R().<method1>(...).<method2>(...).<method3>(...).IP(1.2.3.4)
WARNING! All finishers of 'tRequest' object returns 'tRawResponse' object! It means, that you need manually check if any error is occur and manually decode the raw JSON response. BUT! You can use 'CheckError' and 'DecodeTo' methods of 'tRawResponse' class. In truth, the 'IP', 'IPs' and 'UpdateMe' methods of 'Client' works that way.
type Response ¶
type Response struct { IP string `json:"ip"` Hostname string `json:"hostname"` Type string `json:"type"` ContinentCode string `json:"continent_code"` ContinentName string `json:"continent_name"` CountryCode string `json:"country_code"` CountryName string `json:"country_name"` RegionCode string `json:"region_code"` RegionName string `json:"region_name"` City string `json:"city"` Zip string `json:"zip"` Latitide float32 `json:"latitude"` Longitude float32 `json:"longitude"` Location *tResponseLoc `json:"location"` Timezone *tResponseTimeZone `json:"time_zone"` Currency *tResponseCurrency `json:"currency"` Connection *tResponseConnection `json:"connection"` Security *tResponseSecurity `json:"security"` }
'Response' represents the golang view of Web API response. Fields 'Location', 'Timezone', 'Currency', 'Connection', 'Security' might be nil, if you didn't request it earlier using 'Fields' method of 'Client' or 'tRequest' classes, or 'ParamFields' parameter of 'Client' constructor ('New' function).
NOTE! If you do not understand what data stored in field, read the docs of the consts 'Field...' (above).
func IP ¶
'IP' is the same as 'IP' of any 'Client' instance but only for default client. See docs for 'Client.IP' method and 'DefaultClient' variable for details.