{"id":36820952,"url":"https://github.com/breinify/brein-api-library-node","last_synced_at":"2026-01-12T14:01:08.918Z","repository":{"id":71351020,"uuid":"63641093","full_name":"Breinify/brein-api-library-node","owner":"Breinify","description":"Breinify's Node.js API Library","archived":false,"fork":false,"pushed_at":"2022-09-15T01:50:23.000Z","size":2562,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-11-03T19:19:38.559Z","etag":null,"topics":["analytics","breinify","events","geocoding","holidays","ipaddress","ipaddress-to-address","ipaddresses","location-service","reverse-geocoding","temporal-data","timezone","weather"],"latest_commit_sha":null,"homepage":"https://www.breinify.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Breinify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-07-18T22:20:02.000Z","updated_at":"2022-09-15T01:50:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"535b3926-2a0f-4c7b-8355-8626c5adf844","html_url":"https://github.com/Breinify/brein-api-library-node","commit_stats":{"total_commits":98,"total_committers":7,"mean_commits":14.0,"dds":"0.47959183673469385","last_synced_commit":"15bf51fa93cf81047a8dfb60aadd5e430cde32c1"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Breinify/brein-api-library-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Breinify%2Fbrein-api-library-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Breinify%2Fbrein-api-library-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Breinify%2Fbrein-api-library-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Breinify%2Fbrein-api-library-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Breinify","download_url":"https://codeload.github.com/Breinify/brein-api-library-node/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Breinify%2Fbrein-api-library-node/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28340211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","breinify","events","geocoding","holidays","ipaddress","ipaddress-to-address","ipaddresses","location-service","reverse-geocoding","temporal-data","timezone","weather"],"created_at":"2026-01-12T14:00:26.805Z","updated_at":"2026-01-12T14:01:08.903Z","avatar_url":"https://github.com/Breinify.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://www.breinify.com/img/Breinify_logo.png\" alt=\"Breinify API JavaScript Library\" width=\"250\"\u003e\n\u003c/p\u003e\n\n\n# Breinify's API Library\n[![npm version](https://badge.fury.io/js/breinify-node.svg)](https://badge.fury.io/js/breinify-node)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\u003csup\u003eFeatures: **Temporal Data**, **(Reverse) Geocoding**, **Events**, **Weather**, **Holidays**, **Analytics**\u003c/sup\u003e\n\nThis library utilizes [Breinify's API](https://www.breinify.com) 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.\n\n**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.\n\n**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).\n\n## Getting Started\n\n### Retrieving an API-Key\n\nFirst of all, you need a valid API-key, which you can get for free at [https://www.breinify.com](https://www.breinify.com). In the examples, we assume you have the following API key:\n\n**938D-3120-64DD-413F-BB55-6573-90CE-473A**\n\nIt is recommended to use signed messages when utilizing the Node.js library. A signed messages ensures, that the request is authorized. To activate signed message ensure that `Verification Signature` is enabled for your key (see [Breinify's API Docs](https://www.breinify.com/documentation) for further information).\nIn this documentation we assume that the following secret is attached to the API key and used to sign a message.\n\n**utakxp7sm6weo5gvk7cytw==**\n\n\n### Including the Library\n\nThe library is available on [npm](https://www.npmjs.com/package/breinify-node) and can be easily added using:\n\n```shell\nnpm install breinify-node --save\n```\n\n### Configuring the Library\n\nWhenever the library is used, it needs to be configured, i.e., the configuration defines which API key and which secret \n(if signed messages are enabled, i.e., `Verification Signature` is checked) to use.\n\n```javascript\nvar Breinify = require('breinify-node');\nvar breinify = new Breinify({ \n    apiKey: '938D-3120-64DD-413F-BB55-6573-90CE-473A', \n    secret: 'utakxp7sm6weo5gvk7cytw==' \n});\n\n// use the breinify instance, see the following usage examples\n```\n\n## Activity: Selected Usage Examples\n\nThe `/activity` 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](https://github.com/Breinify/brein-api-library-ios), [Android](https://github.com/Breinify/brein-api-library-android), [Java](https://github.com/Breinify/brein-api-library-java), [JavaScript](https://github.com/Breinify/brein-api-library-javascript-browser), [ruby](https://github.com/Breinify/brein-api-library-ruby), [php](https://github.com/Breinify/brein-api-library-php), [python](https://github.com/Breinify/brein-api-library-python)).\n\n### Send `login` Activity\n\nThe example shows, how to send a login activity, reading the data from an request. In general, activities are added to the interesting measure points within your applications process (e.g., `login`, `addToCart`, `readArticle`). The endpoint offers analytics and insights through Breinify's dashboard.\n\n```javascript\n// the req object may be passed, e.g., using express:\n//   app.post('/login', function(req, res) { ... });\n\nvar user = {\n    'sessionId': req.sessionID,\n    'email': req.body.email\n};\n\nbreinify.activity(user, 'login');\n```\n\n### Send Activities with Additional Information (`tags`)\n\nIt is also possible to send additional information with an activity, e.g., which items were added to a cart. More precise information help to group or filter when analyzing the collected data.\n\n```javascript\n// the req object may be passed, e.g., using express:\n//   app.post('/login', function(req, res) { ... });\n\nvar user = {\n    'sessionId': req.sessionID\n};\n\nvar tags = {\n    'productIds': [ req.productId ],\n    'productPrices': [ req.productPrice ]\n};\n\nbreinify.activity(user, 'addToCart', null, tags);\n```\n\n## TemporalData: Selected Usage Examples\n\n### IP-Resolving (retrieve information for an IP-address)\n\nOne of the use cases of the `/temporalData` endpoint is to retrieve information about a specific IP-address. \n\n```javascript\nBreinify.temporalData('204.28.127.66', function(data) {\n    // use the returned data\n});\n```\n\nAn example is available on [runkit.com](https://runkit.com/breinify-stage/looking-up-ip-data). The retrieved\ninformation contains, other than just a location, weather, holiday, time, and events.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/Breinify/brein-api-library-node/master/documentation/img/sample-ip-lookup.png\" alt=\"IP LookUp\" width=\"500\"\u003e\u003cbr/\u003e\n  \u003csup\u003eScreenshot of the result resolving the IP 204.28.127.66\u003c/sup\u003e\n\u003c/p\u003e\n\n### Geocoding (retrieve information from text)\n\nSometimes you need specific information for a city or some textual description of a location. The following example shows\nhow to retrieve the temporal information (i.e., location, events, holidays, time) from a text. For example, did you know\nwhere `Bemidji` and how the current weather is?\n\n```javascript\nBreinify.temporalData({ location: { text: 'Bemidji' }}, function(data) {\n    // use the returned data\n});\n```\n\nThe above example is also available on [runkit.com](https://runkit.com/breinify-stage/geocoding-free-text). Now we know, \n`Bemidji` is a city in Minnesota, \"close\" to the Canadian border.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/Breinify/brein-api-library-node/master/documentation/img/sample-geocoding-free-text.png\" alt=\"Free-Text Geocoding\" width=\"500\"\u003e\u003cbr/\u003e\n  \u003csup\u003eScreenshot of the result resolving the text Bemidji\u003c/sup\u003e\n\u003c/p\u003e\n\n### Reverse Geocoding (retrieve information from coordinates)\n\nThe `/temporalData` endpoint enables you to perform reverse geocoding. To do so, simple pass in the known latitude and longitude\ninto the request.\n\n```javascript\nBreinify.temporalData(40.4406, -79.9959, function(data) {\n    // use the returned data\n});\n```\n\nAn example for Pittsburgh (the coordinates used in the code-snippet), is available on [runkit.com](https://runkit.com/breinify-stage/reverse-geocoding-lati-long),\nutilizing the latest version of the library. The result contains besides the actual location (as shown in the following screenshot),\ninformation about the current weather, current events or regional and global holidays.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/Breinify/brein-api-library-node/master/documentation/img/sample-reverse-geocoding-lat-lon.png\" alt=\"Reverse Geocoding\" width=\"500\"\u003e\u003cbr/\u003e\n  \u003csup\u003eScreenshot of the result (location only) resolving the coordinates 40.4406° N, 79.9959° W\u003c/sup\u003e\n\u003c/p\u003e\n\nThe endpoint also offers the possibility to retrieve `GeoJson` instances for, e.g., the neighborhood (if available), the city, or the state. The following\ncode-snippets shows how a `GeoJson` can be retrieved.\n\n```javascript\nvar loc = {\n  latitude: 40.7608, \n  longitude: -111.8910,\n  shapeTypes: ['CITY']\n};\n\nBreinify.temporalData({ location: loc }, function(data) {\n    console.log(data.location.geojson.CITY);\n});\n```\n\nThe example with `GeoJson` is also available on [runkit.com](https://runkit.com/breinify-stage/reverse-geocoding-geojson). The following\nscreenshots shows the result.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/Breinify/brein-api-library-node/master/documentation/img/sample-geojson.png\" alt=\"Reverse Geocoding\" width=\"500\"\u003e\u003cbr/\u003e\n  \u003csup\u003eScreenshot of the result visualizing the GeoJson of the city located at 40.7608° N, 111.8910° W\u003c/sup\u003e\n\u003c/p\u003e\n\n## Further links\n\nTo understand all the capabilities of Breinify's API, you can find further information:\n- the [library documentation](documentation/api.md),\n- the [full API documentation](https://www.breinify.com/documentation/index.html),\n- [Breinify's Website](https://www.breinify.com).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreinify%2Fbrein-api-library-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbreinify%2Fbrein-api-library-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreinify%2Fbrein-api-library-node/lists"}