Share reports
Give recipients access to a report and revoke access when needed.
Use a share to give a client access to a report. The publishing integration manages the share with its account's bearer key. The recipient reads the report with a temporary share token and needs no GeoRanker API key.
Create or update a share
Send POST /api/shares with the report UUID in reportId and its type in reportType. You can set a password and restrict access to addresses in emails. This example shows a rank tracker share restricted to one illustrative email address. Replace the UUID and email before running it.
curl --request POST 'https://seoapi.georanker.com/api/shares' \
--header "Authorization: Bearer $SEO_TOOLS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"reportId":"130d9669-f1fd-4393-884b-38cff7fa17db","reportType":"rank_tracker","emails":["[email protected]"]}'
The success response is HTTP 200 with an ok boolean. Read the current settings with GET /api/shares/{reportId} using the same bearer authentication.
Read a report as a recipient
- Get the share metadata from
GET /api/public/shares/{reportId}. This request is unauthenticated. The response includesreportTypeandhasPassword. - Exchange the credentials required by that share at
POST /api/public/shares/{reportId}/token. The JSON body acceptsemailandpassword. A valid exchange returns HTTP 200 with atokenstring. Invalid credentials return HTTP 401. - Send the temporary token in the
tokenquery parameter on the matching public report endpoint. Keep the token and token-bearing URLs private.
For the email-restricted rank tracker example, set REPORT_ID to the shared report UUID. The following commands use jq to read the token and curl to encode it in the results request.
SHARE_TOKEN=$(curl --fail --silent --show-error \
--request POST "https://seoapi.georanker.com/api/public/shares/$REPORT_ID/token" \
--header 'Content-Type: application/json' \
--data '{"email":"[email protected]"}' | jq -er '.token')
curl --get "https://seoapi.georanker.com/api/public/ranktracker/$REPORT_ID/keywords" \
--data-urlencode "token=$SHARE_TOKEN"
Supported report types and public read paths
All paths below use GET. Substitute the shared report UUID for {id} and pass the token on each request.
Value of reportType | Report | Additional results |
|---|---|---|
rank_tracker | /api/public/ranktracker/{id} | /api/public/ranktracker/{id}/keywords and /api/public/ranktracker/{id}/keyword-serp/{serpId} |
heatmap | /api/public/heatmap/{id} | /api/public/heatmap/{id}/results |
serp_snapshot | /api/public/serp-snapshot/{id} | /api/public/serp-snapshot/{id}/results |
onpage | /api/public/onpage/{id} | Report endpoint only |
keyword_research | /api/public/keywords/{id} | Report endpoint only |
Revoke a share
The publishing integration can revoke the share with DELETE /api/shares/{reportId} using its bearer key. A successful request returns HTTP 200 with an ok boolean.