Locations

The Locations API manages the locations a project tracks. A location is a country, optionally narrowed down to a city or region inside it. Every location is checked with all of the project’s engines, and prompts are assigned to the locations they are tracked in.

Using the SE Visible API, you can:

• list a project’s locations together with the plan’s location allowance
• add a country-level or city-level location to a project
• move a location to another country or city
• delete a location from a project

To track a city or region, look up its geo_location_id with the Geo autocomplete endpoints first.

All endpoints are relative to the base URL https://api.seranking.com/v1/se-visible.

List project locations

GET https://api.seranking.com/v1/se-visible/projects/{project_id}/locations

Returns the locations tracked by a project, oldest first, together with how many locations the project uses and how many its plan allows.

Note:

• max_locations is the plan allowance for this project, not across the organisation. This differs from the organisation-wide prompt limit returned by Get subscription (limits.prompts).
• A project left with more locations than its allowance, for example after a plan downgrade, has its checks paused until the excess locations are removed. Nothing is deleted, and the locations and their history stay readable.

Request parameters

Path parameters

Request example

curl -X GET 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/locations' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a JSON object with the project’s locations and its location usage.

Response example

{

  "locations": [

    {

      "id": "9f8c2b1a-1e2d-4c3b-8a7f-0d1e2c3b4a59",

      "country_code": "US",

      "geo_location_id": null,

      "city": null,

      "prompts_count": 56

    },

    {

      "id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081",

      "country_code": "UK",

      "geo_location_id": 42,

      "city": "Manchester, England, United Kingdom",

      "prompts_count": 0

    }

  ],

  "locations_used": 2,

  "max_locations": 1

}

Add a location

POST https://api.seranking.com/v1/se-visible/projects/{project_id}/locations

Adds a location to a project and sets it up for every engine and language the project currently tracks. Send only country_code to track the whole country, or add a geo_location_id to track a city or region inside it.

Note:

• Existing prompt assignments are not copied, so a newly added location has no prompts.
• Adding a place that was deleted before creates a new location. The deleted one stays deleted with its history.
• Get geo_location_id from Search cities and regions, using the suggestions for the same country. Only the existence of the ID is validated: the API cannot check that the point actually lies in country_code.
• If the project has reached its location allowance, the request returns 403 with error_code insufficient_limit and limit_type llm_locations.
• If the project already tracks the same country and city, the request returns 409 with error_code location_duplicate.

Request parameters

Path parameters

Request body

Request example

curl -X POST 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/locations' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "country_code": "UK",

    "geo_location_id": 42

  }'

Response parameters

If successful, the server returns 201 Created with the added location.

Response example

{

  "id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081",

  "country_code": "UK",

  "geo_location_id": 42,

  "city": "Manchester, England, United Kingdom",

  "prompts_count": 0

}

Update a location

PATCH https://api.seranking.com/v1/se-visible/projects/{project_id}/locations/{location_id}

Replaces a location with one that tracks the given country and city. The location’s engines and prompt assignments move over unchanged, so future checks run for the new place, while everything collected so far keeps the old location as its label.

Note:

• The response carries a new location ID and the old one is deleted. Use the returned id from now on.
• Always send the target place in full: omitting geo_location_id or sending null returns the location to country-level tracking.
• Sending the location’s current place changes nothing and returns the location as is.
• If the project already tracks that place, the request returns 409 with error_code location_duplicate.
• While the project is being checked, the request returns 409 with error_code location_check_in_progress. Retry once the check has finished, otherwise results still on their way would be filed under the new place.

Request parameters

Path parameters

Request body

Request example

curl -X PATCH 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/locations/1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "country_code": "UK",

    "geo_location_id": null

  }'

Response parameters

If successful, the server returns the replacement location. Its id is the one to use from now on.

Response example

{

  "id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081",

  "country_code": "UK",

  "geo_location_id": null,

  "city": null,

  "prompts_count": 56

}

Delete a location

DELETE https://api.seranking.com/v1/se-visible/projects/{project_id}/locations/{location_id}

Deletes a location from a project and unassigns it from every prompt it is assigned to. The prompts themselves stay: a prompt left without locations is simply no longer tracked.

Note:

• If the location is assigned to prompts, the request returns 409 with error_code location_in_use and the number of affected prompts in prompts_count. Repeat the request with confirm=true to delete it anyway, so you can warn the user first.
• The last location of a project cannot be deleted. Attempting to do so returns 422 with error_code cannot_remove_last_location.

Request parameters

Path parameters

Query parameters

Request example

curl -X DELETE 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/locations/1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081?confirm=true' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns 204 No Content with an empty body.