{"id":16339874,"url":"https://github.com/yuvalherziger/quintly-java-api","last_synced_at":"2025-10-25T23:32:25.572Z","repository":{"id":84675181,"uuid":"111191146","full_name":"yuvalherziger/quintly-java-api","owner":"yuvalherziger","description":"A light-weight Java library for quintly's Social Media Analytics API","archived":false,"fork":false,"pushed_at":"2018-02-21T21:13:56.000Z","size":116,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-07T12:49:38.345Z","etag":null,"topics":["api","java","qql","quintly","social-media"],"latest_commit_sha":null,"homepage":"","language":"Java","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/yuvalherziger.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-18T09:01:06.000Z","updated_at":"2019-04-04T14:30:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"269345ea-b6cb-4117-b9cb-749ac81de545","html_url":"https://github.com/yuvalherziger/quintly-java-api","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yuvalherziger/quintly-java-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuvalherziger%2Fquintly-java-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuvalherziger%2Fquintly-java-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuvalherziger%2Fquintly-java-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuvalherziger%2Fquintly-java-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuvalherziger","download_url":"https://codeload.github.com/yuvalherziger/quintly-java-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuvalherziger%2Fquintly-java-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281038650,"owners_count":26433634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["api","java","qql","quintly","social-media"],"created_at":"2024-10-10T23:55:23.400Z","updated_at":"2025-10-25T23:32:25.567Z","avatar_url":"https://github.com/yuvalherziger.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📈 quintly-java-api\n[![codecov](https://codecov.io/gh/yuvalherziger/quintly-java-api/branch/master/graph/badge.svg?token=Tnad7lN8Cb)](https://codecov.io/gh/yuvalherziger/quintly-java-api)\n[![Codeship Status for yuvalherziger/quintly-java-api](https://app.codeship.com/projects/5d4f67e0-b284-0135-f1e6-124eec6b3035/status?branch=master)](https://app.codeship.com/projects/258096)\n\nA light-weight Java library for quintly's Social Media Analytics API. \nFor more information about the API, see [quintly's API documentation](https://api.quintly.com/).\n\n## Table of Contents\n\n   * [What's quintly?](#whats-quintly)\n   * [Getting started](#getting-started)\n      * [Build](#build)\n      * [Tests](#tests)\n      * [Examples:](#examples)\n         * [List-Profiles endpoint:](#list-profiles-endpoint)\n         * [Custom Response Model:](#custom-response-model)\n   * [What's next?](#whats-next)\n   * [Contributing](#contributing)\n   * [Copyright and license](#copyright-and-license)\n\n## What's quintly?\n[quintly](https://www.quintly.com) is a _Professional Social Media Analytics_ platform that allows you to track, benchmark and optimize your social media performance. One of the services that quintly offers is its API, which acts as the gateway to **all** of the available metrics through quintly's tool.\n \nquintly allows you to track profiles on Facebook, Twitter, Instagram, YouTube, LinkedIn, Google+, Pinterest as well as RSS feeds. That includes both publicly available statistics and private-level statistics such as Facebook Insights, Facebook Ads, Instagram Insights, YouTube Analytics and Twitter Analytics.\n \n## Getting started\n\n### Build\nTo build the project from gradle wrapper, run:\n```bash\n~ ./gradlew build\n```\nOtherwise, from a [global gradle installation](https://gradle.org/install/):\n```bash\n~ gradle build\n```\n\n### Tests\n```bash\n~ ./gradlew test # or 'gradle test' with a global gradle installation\n```\n\n### Examples:\n\n#### List-Profiles endpoint:\nThe **List-Profiles** endpoint is perhaps the simplest and most useful endpoint for a quick start with the quintly API.\nThe response of this endpoint is a list of all the social media profiles under your quintly account. The endpoint can also be narrowed down to a specific group ID within the account.\n  \n```java\nimport com.quintly.api.endpoint.ListProfiles;\nimport com.quintly.api.entity.Profile;\nimport com.quintly.api.exception.*;\nimport com.quintly.api.factory.ClientFactory;\nimport java.io.IOException;\nimport java.util.ArrayList;\n \nclass MyApp {\n    \n    public static void main(String[] args) throws IOException, IncompatibleGetterException, BadResponseException {\n        \n        ArrayList\u003cProfile\u003e profiles = ClientFactory.createClient()\n                .executeGet(\n                        new Credentials(1, \"client-secret\"),\n                        new ListProfiles() // or 'new ListProfiles(10)' for a specific group ID\n                ).getProfilesCollection().getData();\n        \n        // Dig in:\n        for (Profile profile : profiles) {\n            System.out.println(profile.getName());\n            System.out.println(profile.getPlatformType());\n            // ...\n        }\n    }\n}\n```\n\n#### Custom Response Model:\nThe thing that makes the QQL endpoint of quintly's API different from its other endpoints is that the response's structure is a direct derivative of the metric or QQL query that's requested, thus it's not predictable. For that reason, the library does not implement a specific QQL response format.\nThe following QQL query is a legitimate query, where the `profileId`, `time` and `fans` data points are selected from the `Facebook` data source (but one could also apply column aliases and change the attribute names in the response):\n\n```sql\nSELECT profileId, time, fans FROM facebook\n```\n\nThe response from the API would be along the following lines:\n\n```json\n{\n    \"success\": true,\n    \"data\": [{\n            \"profileId\": 123,\n            \"time\": \"2017-11-29 00:00:00\",\n            \"fans\": 1947182\n        },\n        {\n            \"profileId\": 123,\n            \"time\": \"2017-11-30 00:00:00\",\n            \"fans\": 1947310\n        }\n    ]\n}\n```\n\nThe library allows you to pass down your custom response model, to create a clear interface between the raw response and your application's models.\nLet's implement the following two classes, the first one for a single data node and the second one for the upper level response:\n\n```java\npackage com.domain.myapp;\n\npublic class MyCustomNode {\n    private int profileId;\n    private String time;\n    private int fans;\n    public int getProfileId()   { return profileId; }\n    public String getTime()     { return time;      }\n    public int getFans()        { return fans;      }\n}\n```\n \n ```java\npackage com.domain.myapp; \nimport java.util.ArrayList;\n \npublic class MyCustomResponseModel {\n    private boolean success;\n    private ArrayList\u003cMyCustomNode\u003e data;\n \n    public boolean isSuccess() {\n        return success;\n    }\n \n    public ArrayList\u003cMyCustomNode\u003e getData() {\n        return data;\n    }\n }\n```\n\nNow, all that's left to do is to use the library's custom parser and pass down your custom model, like so:\n\n```java\nimport com.quintly.api.endpoint.Qql;\nimport com.quintly.api.exception.BadResponseException;\nimport com.quintly.api.factory.ClientFactory;\nimport java.io.IOException;\nimport java.util.ArrayList;\nimport java.util.Arrays;\nimport java.util.Date;\nimport java.util.List;\n \nclass MyApp {\n    \n    public static void main(String[] args) throws IOException, BadResponseException {\n        // create a list of the profiles we want to fetch from the api in the above metric:\n        List\u003cInteger\u003e profileIds = new ArrayList\u003cInteger\u003e(Arrays.asList(123));\n        // Submit the request:\n        MyCustomResponseModel myCustomResponseModel = (MyCustomResponseModel) ClientFactory.createClient()\n                .executeGet(\n                        new Credentials(1, \"client-secret\"),\n                        new Qql(\n                                new Date(1506816000000L),\n                                new Date(),\n                                profileIds,\n                                \"SELECT profileId, time, fans FROM facebook\"\n                        )\n                ).getData(new ModelParser\u003c\u003e(MyCustomResponseModel.class));\n        // Dig in:\n        for (MyCustomNode dataNode : myCustomResponseModel.getData()) {\n            System.out.println(dataNode.getTime());\n            System.out.println(dataNode.getFans());\n        }\n    }\n}\n```\n\n## What's next?\n\n- `config.yml.dist` and allow loading configurations from a resource\n- Add examples package\n- More exception types\n\n## Contributing\nFeel free to submit pull requests, issues and ideas 💡\n\n## Copyright and license\nMIT License\n\nCopyright (c) 2018 Yuval Herziger, quintly GmbH\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuvalherziger%2Fquintly-java-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuvalherziger%2Fquintly-java-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuvalherziger%2Fquintly-java-api/lists"}