Authentication

OAuth 2.0 (opens in a new tab) is the primary method for users to access the Xweather Phrases API in order to track usage and keep users' data secure. Since the Xweather Phrases API does not provide access to private user account data and information, all general requests to the Phrases API only require userless access in which you pass your unique API access ID and secret key with every request.

Each third-party application must register itself in order to obtain the proper API credentials. Additionally, each credential is tied to a unique application identifier for the user's application, which for the web is simply the domain that API requests will be made from, such as https://somedomain.com. For iOS applications, this identifier will be the full bundle identifier for their application, e.g. com.somedomain.SomeAppName. Every Phrases API request will include these identifiers that the API will validate before returning a response.

For example, every request you make to the API must include at least your assigned client ID and secret key for the application in one of the following ways.

Assigning a client_id and client_secret as query parameters to the request:

https://phrases.api.xweather.com/alerts/98109?client_id={client_id}&client_secret={client_secret}

Or optionally, assigning X-Client-Id and X-Client-Secret as headers to the request. Please note that these options cannot be mixed and matched.

GET /alerts/98109 HTTP/1.1
Host: phrases.api.xweather.com
X-Client-Id: client_id
X-Client-Secret: client_secret

You can still include your custom options with the request:

https://phrases.api.xweather.com/alerts/98109?units=metric&language=fi&client_id={client_id}&client_secret={client_secret}

Namespace Access Restrictions

When you register a new application to use your weather API account, you will be required to provide the namespace under which the secret key you are creating will be used. This will restrict all requests using that client ID and secret key combination to the namespace you provided within your account area.

For web requests, the namespace should be the top-level domain (TLD) from which the requests will be made, such as mydomain.com or *.mydomain.com. Note that if you provide a subdomain, such as sub.mydomain.com, all requests will be restricted to that specific subdomain instead of the top-level domain. However for mobile applications, specifically iOS and Android, your namespace should be the bundle identifier for your application that conforms to the Reverse DNS naming convention (e.g., com.mydomain.MyProject).

Secure API Access

When secure connections to the weather API are required, the HTTPS protocol can be utilized with the API, by querying with “https” in place of “http”. For example:

https://phrases.api.xweather.com/alerts/98109?units=metric&language=fi&client_id={client_id}&client_secret={client_secret}