Skip to content

Commit 719f1da

Browse files
jiehao71727jiehao71727
committed
Add Facebook Pages API examples
0 parents  commit 719f1da

21 files changed

Lines changed: 645 additions & 0 deletions

‎.env.example‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
SOCQ_API_KEY=your-api-key
2+
SOCQ_BASE_URL=https://api.socq.ai

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
* text=auto eol=lf
2+
*.png binary
3+
*.jpg binary
4+
*.jpeg binary
5+
*.webp binary

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* @jiehao71727

‎.github/workflows/check.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Check examples
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
check:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
20+
- name: Set up Node.js
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: "22"
24+
25+
- name: Set up Python
26+
uses: actions/setup-python@v5
27+
with:
28+
python-version: "3.12"
29+
30+
- name: Check examples
31+
run: npm run check

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.env
2+
.env.*
3+
!.env.example
4+
node_modules/
5+
__pycache__/
6+
*.py[cod]
7+
.DS_Store
8+
coverage/
9+
output/

‎.socq-example.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"schemaVersion": 1,
3+
"endpointId": "facebook-pages",
4+
"templateVersion": "2.0.0",
5+
"method": "POST",
6+
"path": "/v1/facebook/pages",
7+
"landingPage": "https://socq.ai/apis/facebook/pages",
8+
"docsPage": "https://docs.socq.ai/api-manual/facebook/pages",
9+
"generatedFrom": "SocQAPI/socq-example-template"
10+
}

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 SocQ
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.PHONY: check
2+
3+
check:
4+
npm run check

‎README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Facebook Pages API examples for SocQ
2+
3+
[![Facebook Pages API](https://img.shields.io/badge/API-Facebook%20Pages%20API-F64C31)](https://socq.ai/apis/facebook/pages?utm_source=github&utm_medium=repository&utm_campaign=facebook-pages-api)
4+
[![API documentation](https://img.shields.io/badge/Docs-docs.socq.ai-111827)](https://docs.socq.ai/api-manual/facebook/pages)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-2563EB)](LICENSE)
6+
[![Check examples](https://github.com/SocQAPI/facebook-pages-api/actions/workflows/check.yml/badge.svg)](https://github.com/SocQAPI/facebook-pages-api/actions/workflows/check.yml)
7+
8+
Collect public Facebook Page profile details, contact fields, visible follower and like counts, and page metadata from one or more Page URLs.
9+
10+
[Try Facebook Pages API](https://socq.ai/apis/facebook/pages?utm_source=github&utm_medium=repository&utm_campaign=facebook-pages-api)
11+
· [Get an API key](https://socq.ai/dashboard/api-key?utm_source=github&utm_medium=repository&utm_campaign=facebook-pages-api)
12+
· [Documentation](https://docs.socq.ai/api-manual/facebook/pages)
13+
· [All SocQ examples](https://github.com/SocQAPI/socq-examples)
14+
15+
## Use cases
16+
17+
- **Brand page monitoring:** Collect public Page identity, category, contact, and audience metrics for owned or competitor Page tracking.
18+
- **Content performance research:** Compare public Page categories, descriptions, contact coverage, follower counts, ratings, and visible audience signals.
19+
- **Reporting and BI pipelines:** Send normalized public Page records into dashboards, spreadsheets, warehouses, or product review tools.
20+
- **Media archive workflows:** Store Page URLs, images, descriptions, contact fields, and visible metrics for later review or reporting.
21+
22+
## API behavior
23+
24+
- Submit one or more publicly accessible Facebook Page URLs.
25+
- Each accessible Page can produce one normalized record.
26+
- Contact fields, ratings, reviews, images, and audience metrics are optional public fields.
27+
- Restricted, removed, or login-only Page content is outside the endpoint scope.
28+
29+
All requests use the shared asynchronous flow:
30+
31+
```text
32+
submit -> task_id -> poll task -> read every cursor page -> save results
33+
```
34+
35+
## Quick start
36+
37+
```bash
38+
cp .env.example .env
39+
export SOCQ_API_KEY="your-api-key"
40+
```
41+
42+
Run the complete Node.js workflow:
43+
44+
```bash
45+
cd node
46+
npm start
47+
```
48+
49+
Run the complete Python workflow:
50+
51+
```bash
52+
python3 -m pip install -r python/requirements.txt
53+
python3 python/main.py
54+
```
55+
56+
Both examples load `payload.example.json`, retry transient API responses, wait
57+
for task completion, read every cursor page, and save a public Page directory with identity, contact, and audience fields to
58+
`output/results.json`.
59+
60+
Never expose `SOCQ_API_KEY` in browser code, mobile apps, public repositories,
61+
screenshots, fixtures, or logs.
62+
63+
## Request
64+
65+
```http
66+
POST https://api.socq.ai/v1/facebook/pages
67+
Authorization: Bearer <SOCQ_API_KEY>
68+
Content-Type: application/json
69+
```
70+
71+
```json
72+
{
73+
"urls": [
74+
"https://www.facebook.com/example-page"
75+
]
76+
}
77+
```
78+
79+
The submit response contains `data.task_id`. Poll the task endpoint until
80+
`data.status` becomes `succeeded` or `failed`, then continue with
81+
`data.results.next_cursor` while `data.results.has_more` is `true`.
82+
83+
## Complete workflow example
84+
85+
The Node.js and Python programs implement the production-shaped happy path:
86+
87+
1. Load and validate configuration.
88+
2. Submit the endpoint-specific payload.
89+
3. Retry rate-pressure and transient server responses with bounded backoff.
90+
4. Poll the asynchronous task with a ten-minute application timeout.
91+
5. Stop cleanly on a failed task and surface the public error message.
92+
6. Read all cursor pages instead of silently returning only the first page.
93+
7. Write a stable JSON artifact containing task metadata and normalized records.
94+
95+
Use the synthetic files in `fixtures/` for tests and documentation. They do
96+
not contain customer, account, or production data.
97+
98+
## Production notes
99+
100+
See [`docs/production-notes.md`](docs/production-notes.md) for validation,
101+
retry, timeout, pagination, deduplication, logging, and endpoint-specific
102+
guidance.
103+
104+
## Responsible use and platform scope
105+
106+
- Use only publicly accessible Facebook Pages, posts, comments, and fields supported by the selected endpoint.
107+
- Do not use the examples to access private profiles, closed groups, restricted content, login-only surfaces, or authentication controls.
108+
- SocQ is not an official API of the represented social platform and is not affiliated with or endorsed by that platform.
109+
- Before production use, assess the laws, platform terms, privacy obligations, and retention requirements that apply to your organization and use case.
110+
- Collect only the fields needed for a defined purpose, restrict access, set retention periods, and support correction or deletion workflows where required.
111+
- Platform names and trademarks belong to their respective owners.
112+
113+
This section describes the public-data boundary; it is not legal advice or a
114+
guarantee that every use case is permitted in every jurisdiction.
115+
116+
## Repository contents
117+
118+
| Path | Purpose |
119+
| --- | --- |
120+
| [`curl/request.md`](curl/request.md) | Copy-paste submit, poll, and pagination requests |
121+
| [`node/index.mjs`](node/index.mjs) | Complete Node.js workflow |
122+
| [`python/main.py`](python/main.py) | Complete Python workflow |
123+
| [`payload.example.json`](payload.example.json) | Safe endpoint-specific request body |
124+
| [`fixtures/`](fixtures) | Synthetic submit and task response shapes |
125+
| [`docs/production-notes.md`](docs/production-notes.md) | Production integration guidance |

‎SECURITY.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Security policy
2+
3+
Report vulnerabilities privately to [support@socq.ai](mailto:support@socq.ai).
4+
Do not open public issues containing credentials, customer data, production
5+
task payloads, callback secrets, internal hosts, or private account data.
6+
7+
This repository must never contain real `SOCQ_API_KEY` values. Use
8+
`.env.example`, placeholder task IDs, and synthetic fixtures only.

0 commit comments

Comments
 (0)