GeoRanker Docs
SEO Tools APIProjects and keyword lists

Projects and keyword lists

Find campaigns, read dashboard activity, and manage saved keywords.

A project is a campaign. Use its UUID to find reports, read dashboard activity and save keyword lists for the website you track. The examples assume your SEO Tools API key is available in SEO_TOOLS_API_KEY.

Find or create a project

List the organization's projects with GET /api/projects. This example supplies the q search term and filters by active status. Save the matching projects[].id as PROJECT_ID for later requests.

curl --get 'https://seoapi.georanker.com/api/projects' \
  --header "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  --data-urlencode 'status=active' \
  --data-urlencode 'q=Example Hotels'
  • To create a campaign, send POST /api/projects with {"name":"Example Hotels","domain":"example.com"}. The name must have at least two characters. The domain is optional. A successful request returns HTTP 201 with the new UUID in project.id.
  • To read one campaign, use GET /api/projects/{projectId}. To change its name or domain, send either field in a JSON body to PATCH /api/projects/{projectId}. Both return a project object.
  • To archive a campaign, send POST /api/projects/{projectId}/archive. Find archived campaigns using status=archived on the list request. Use POST /api/projects/{projectId}/restore to reactivate one.

Read the project dashboard

RequestResponse
GET /api/projects/{projectId}/dashboard/kpisInteger counts for totalReports, activeMonitors, pendingAlerts and creditsUsed.
GET /api/projects/{projectId}/dashboard/recent-reportsRecent report records in reports.
GET /api/projects/{projectId}/dashboard/recent-alertsRecent alert records in alerts.
POST /api/projects/{projectId}/alerts/mark-all-readMarks every alert for this project as read and returns ok.

Save and maintain a keyword list

Save terms you want to revisit in a named list. Creating the list stores those terms. To run keyword research, submit a separate report request.

curl --request POST "https://seoapi.georanker.com/api/projects/$PROJECT_ID/keyword-lists" \
  --header "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"City hotels","description":"Terms for the autumn campaign","keywords":[{"term":"hotels in Lisbon"},{"term":"hotels in Porto"}]}'

The required fields are name and keywords. HTTP 201 returns the list UUID in id. Use that ID for subsequent edits.

TaskRequestBody or result
Find the project's listsGET /api/projects/{projectId}/keyword-listsReturns a lists array.
Read a saved listGET /api/keyword-lists/{id}Returns the list record directly, including its keywords. A keyword can include term, country, volume and tags.
Rename or describe the listPATCH /api/keyword-lists/{id}Send name, description or both.
Add a termPOST /api/keyword-lists/{id}/keywordsFor example, send {"keywords":[{"term":"hotels in Faro"}]}.
Replace the termsPUT /api/keyword-lists/{id}/keywordsSend the complete set of terms to keep in the same keywords format.
Delete the listDELETE /api/keyword-lists/{id}Returns ok on success.

Viewers receive HTTP 403 when creating or deleting a list. Members can delete lists they created. For deletion, HTTP 404 can mean the list is missing or the caller lacks permission.

SEO Tools API overview