API integration

This is a JSON REST API. You must use different request types depending on what you want to do:

  • GET to retrieve a list of records or details of a single record.
  • POST to create a new record.
  • PUT to update an existing record.
  • PATCH same as PUT except that you do not need to specify all fields, just the ones you want to update.
  • DELETE to delete an existing record.

Response codes can be used to determine the status of the request:

  • 200 Request was successful.
  • 201 New record was successfully created.
  • 204 Empty response. Delete was successful.
  • 400 Bad request. Validation failed. The response body contains details.
  • 401 Authentication failed. Check your API token.

For POST, PUT or PATCH requests, the new/updated object is returned.


Authentication

All requests must be authenticated with your API token (YOUR_TOKEN).
It must be included in the Authorization HTTP header of the request. It should be prefixed with "Token ".
For you that means the header should look like this:
Header name: Authorization
Value: Token YOUR_TOKEN
Authorization: Token YOUR_TOKEN


Implementation and usage

This is a living API, meaning that from time to time we will add new fields and endpoints. You should never ever hard code your program to expect the output in specific order etc.
Something that looks like this today:

{ "name": "example name", "parent": 1 }Might look like this tomorrow:{ "name": "example name", "parent": 1, "tags": [ "tag1", "tag2" ] }Some records contains a slug field. That field is deprecated and will be removed without notice. You should always use the id to reference records.

There is no request throttling, but if you abuse it we will have to throttle your account. Therefor you should always cache requests locally if you expect to make a lot of requests.



Endpoints

You can browse each endpoint with your browser to read more about each one.
Warning: When you browse the API you're playing with live data. Any POST/PUT/DELETE will alter your data.
Endpoints that have an {id} must have that replaced by the id of the record you want to view. Those ids can be found on the list endpoints.

  • List or create organizations
    • https://app.accuranker.com/api/v3/organizations/
  • View, update or delete a organization
    • https://app.accuranker.com/api/v3/organizations/{pk}/
  • List or create groups
    • https://app.accuranker.com/api/v3/groups/
  • View, update or delete a group
    • https://app.accuranker.com/api/v3/groups/{pk}/
  • List or create domains
    • https://app.accuranker.com/api/v3/domains/
  • View, update or delete a domain
    • https://app.accuranker.com/api/v3/domains/{pk}/
  • View, average ranks for a domain
    • https://app.accuranker.com/api/v3/domains/{pk}/average_ranks/
  • List or create keywords for a specific domain
    • https://app.accuranker.com/api/v3/domains/{domain_id}/keywords/
  • View, update or delete a keyword for a specific domain
    • https://app.accuranker.com/api/v3/domains/{domain_id}/keywords/{id}/
  • View competitors for a specific domain
    • https://app.accuranker.com/api/v3/domains/{domain_id}/competitors/
  • List or create keywords
    • https://app.accuranker.com/api/v3/keywords/
  • View, update or delete a keyword
    • https://app.accuranker.com/api/v3/keywords/{id}/
  • List search locales. These are used to tell which country we should search in.
    • https://app.accuranker.com/api/v3/search_locales/
  • List search engines. These are used to tell which search engine the keyword is queried in.
    • https://app.accuranker.com/api/v3/search_engines/
  • List or create competitors.
    • https://app.accuranker.com/api/v3/competitors/
  • View, update or delete a competitor.
    • https://app.accuranker.com/api/v3/competitors/{id}/
  • List a competitors keywords.
    • https://app.accuranker.com/api/v3/competitors/{id}/keywords/


When browsing the endpoints, you can click the OPTIONS button to see which fields are optional and/or read-only.
Read-only fields can not be overwritten, so you do not need to send those when creating or updating records.
Optional fields can be overwritten but they can be left out as well, in which case default values will be used.


Questions?

If something is not working as expected, or you are missing an endpoint, please contact us.