breinify-api

Breinify's API Library

^{Features: Temporal Data, (Reverse) Geocoding, Events, Weather, Holidays, Analytics}

This library utilizes Breinify's API to provide tasks like geocoding, reverse geocoding, weather and events look up, holidays determination through the API's endpoints, i.e., /activity and /temporaldata. Each endpoint provides different features, which are explained in the following paragraphs. In addition, this documentation gives detailed examples for each of the features available for the different endpoints.

Activity Endpoint: The endpoint is used to understand the usage-patterns and the behavior of a user using, e.g., an application, a mobile app, or a web-browser. The endpoint offers analytics and insights through Breinify's dashboard.

TemporalData Endpoint: The endpoint offers features to resolve temporal information like a timestamp, a location (latitude and longitude or free-text), or an IP-address, to temporal information (e.g., timezone, epoch, formatted dates, day-name), holidays at the specified time and location, city, zip-code, neighborhood, country, or county of the location, events at the specified time and location (e.g., description, size, type), weather at the specified time and location (e.g., description, temperature).

Getting Started

Retrieving an API-Key

First of all, you need a valid API-key, which you can get for free at https://www.breinify.com. In the examples, we assume you have the following api-key:

938D-3120-64DD-413F-BB55-6573-90CE-473A

Including the Library

The library can be added as script, using:

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/breinify-api@1.0.15/dist/breinify-api.min.js"></script>

If you want to use the most current snapshot version (only recommended for development purposes), you can also use:

<script type="text/javascript" src="https://rawgit.com/Breinify/brein-api-library-javascript-browser/master/dist/breinify-api.min.js"></script>

If you prefer to use bower the newest version can be installed using:

bower install breinify-api --save

Activity: Selected Usage Examples

The endpoint is used to track the usage of, e.g., an application, an app, or a web-site. There are several libraries available to be used for different system (e.g., iOS, Android, Java, nodeJs, ruby, php, python).

Track jsFiddle Usage

The jsFiddle (ojkvwwd9) shows how to use the endpoint to track the usage of this specific fiddle. There are plenty more use-cases in which the tracking of activities can be useful to understand and enhance a service. There are also several more possibilities on how to add identification, descriptions, categories, or tags. Have a look at the additional documentation.

TemporalData: Selected Usage Examples

Retrieve Client's Information (Location, Weather, Events, Timezone, Time)

The endpoint is capable to retrieve some information about the client, based on client specific information (e.g., the IP-address). The first example uses this information to retrieve some information, like the weather, events, or the timezone.

^{This is a screenshot of the jsFiddle (3wz4u5d1) created on the 29/03/2017 at 8:54 p.m.}

The whole information is retrieved using the following simple JavaScript (see also jsFiddle (3wz4u5d1)):

Breinify.setConfig({ 'apiKey': '938D-3120-64DD-413F-BB55-6573-90CE-473A' });
Breinify.temporalData(function(data) {
    document.getElementById('result').innerHTML = createText(data);
});

Geocoding (resolve Free-Text to Locations)

The library enables you to use the geocoding feature of the temporalData endpoint by passing a free-text and resolving it to an associated location.

var loc = {
  text: 'NYC'
};
 
Breinify.temporalData({ additional: { location: loc }}, false, function(data) {
    // use the returned data
});

The endpoint will return the specific information to the defined location (i.e., the city, the state, and coordinates as latitude/longitude pair). A more advanced example can be found at the jsFiddle (egyhn5fz).

^{Screenshot of the sFiddle (egyhn5fz) resolving the texts: `NYC`, `San Francisco`, `Dallas`, `Miami`, `Bemidji`}

Reverse Geocoding (retrieve GeoJsons for, e.g., Cities, Neighborhoods, or Zip-Codes)

The temporalData endpoint enables you to perform reverse geocoding. To do so, simple pass in the known latitude and longitude into the request.

var loc = {
  latitude: 37.7609295,
  longitude: -122.4194155
};
 
Breinify.temporalData({ additional: { location: loc }}, false, function(data) {
    // use the returned data
});

If you like to get further information or even visualize the country, county, city, or neighborhood the location is in, it is possible to ask for appropriate geoJson instances and utilize them directly in, e.g., leafLet.

var loc = {
  latitude: latLon[0],
  longitude: latLon[1],
  shapeTypes: ['CITY', 'NEIGHBORHOOD']
};
 
Breinify.temporalData({ additional: { location: loc }}, false, function(data) {
    // use the returned data
});

Have a look at jsFiddle (qq4ryw6y) for a complete example.

^{This is a screenshot of the jsFiddle (qq4ryw6y), utilizing leafLet to visualize the resolved geoJsons}

Limitations

The open /temporalData endpoint is limited to US specific locations only. Furthermore, weather specific data is only available for the years 2016 and later.

Further links

To understand all the capabilities of Breinify's API, you can find further information:

• the library documentation,
• the full API documentation,
• Breinify's Website.