GeoRanker Docs
SEO Tools APIShare results

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 includes reportType and hasPassword.
  • Exchange the credentials required by that share at POST /api/public/shares/{reportId}/token. The JSON body accepts email and password. A valid exchange returns HTTP 200 with a token string. Invalid credentials return HTTP 401.
  • Send the temporary token in the token query 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 reportTypeReportAdditional 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.

SEO Tools API overview