GeoHub API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Welcome to the GeoHub API documentation.

Base URL:

https://api.geohub.app/v1

Authentication

HTTP Authentication, scheme: bearer

Bearer tokens are used for all access to the GeoHub API endpoints apart from the /auth and /public-stats endpoints which are publicly accessible.

Auth

The /auth endpoints handle user authentication and password management.

Supports login with email/password, password reset requests, and password reset confirmation. These endpoints are publicly accessible and do not require authentication.

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/auth/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const inputBody = '{
  "email": "test@test.com",
  "password": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('https://api.geohub.app/v1/auth/login',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/auth/login', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://api.geohub.app/v1/auth/login', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://api.geohub.app/v1/auth/login',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/auth/login", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/auth/login");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /auth/login

Login request

Body parameter

{
  "email": "test@test.com",
  "password": "string"
}

Name	In	Type	Required	Description
email	body	string	true	The user's email
password	body	string	true	The user's password

Example responses

200 Response

{
  "idToken": "02958d31-409a-4491-9105-479f48b3c5ca",
  "idTokenExpiry": 0,
  "name": "John Doe",
  "role": "user",
  "Companies": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "name": "Example Company",
      "website": "https://example.com",
      "logoUrl": "https://example.com/logo.png",
      "companyProfile": {
        "name": "Example Company",
        "website": "https://example.com"
      },
      "marketCount": 10,
      "runCount": 10
    }
  ]
}

Status	Meaning	Description	Schema
200	OK	successful operation	Login
401	Unauthorized	unauthorised - invalid login credentials or first login password required	None
404	Not Found	User not found	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Request password reset

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/auth/password-resets/request \
  -H 'Content-Type: application/json'

const inputBody = '{
  "email": "string"
}';
const headers = {
  'Content-Type':'application/json'
};

fetch('https://api.geohub.app/v1/auth/password-resets/request',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/auth/password-resets/request', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json'
}

r = requests.post('https://api.geohub.app/v1/auth/password-resets/request', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
}

result = RestClient.post 'https://api.geohub.app/v1/auth/password-resets/request',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/auth/password-resets/request", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/auth/password-resets/request");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /auth/password-resets/request

Request a password reset code

Accepts an email. If the user is found, generates a reset code, stores the hashed code in the database, and sends an email with a reset link.

Body parameter

{
  "email": "string"
}

Parameters

Name	In	Type	Required	Description
email	body	string	true	The user's email

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
422	Unprocessable Entity	Unprocessable entity - check error message	None

Complete password reset

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/auth/password-resets/confirm \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const inputBody = '{
  "resetCode": "string",
  "newPassword": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('https://api.geohub.app/v1/auth/password-resets/confirm',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/auth/password-resets/confirm', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://api.geohub.app/v1/auth/password-resets/confirm', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://api.geohub.app/v1/auth/password-resets/confirm',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/auth/password-resets/confirm", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/auth/password-resets/confirm");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /auth/password-resets/confirm

Complete password reset using a reset code

Verifies the provided reset code, ensures it's valid and not expired, then updates the user's password. Clears the reset code upon success.

Body parameter

{
  "resetCode": "string",
  "newPassword": "string"
}

Parameters

Name	In	Type	Required	Description
resetCode	body	string	true	The reset code sent to the user's email
newPassword	body	string	true	The new password to set

Example responses

200 Response

{
  "idToken": "02958d31-409a-4491-9105-479f48b3c5ca",
  "idTokenExpiry": 0,
  "name": "John Doe",
  "role": "user",
  "Companies": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "name": "Example Company",
      "website": "https://example.com",
      "logoUrl": "https://example.com/logo.png",
      "companyProfile": {
        "name": "Example Company",
        "website": "https://example.com"
      },
      "marketCount": 10,
      "runCount": 10
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Login
422	Unprocessable Entity	unprocessable entity - check error message	None

Accounts

The /accounts endpoints handle creating, getting and deleting accounts. Only admin users can create and delete accounts.

Create new account

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/accounts \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "name": "string",
  "plan": "free",
  "marketSlots": 10
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/accounts',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/accounts', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/accounts', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/accounts',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/accounts", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/accounts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /accounts

Creates a new account.

Body parameter

{
  "name": "string",
  "plan": "free",
  "marketSlots": 10
}

Parameters

Name	In	Type	Required	Description
name	body	string	true	The name of the account
plan	body	string	true	The plan of the account
marketSlots	body	integer	true	The number of market slots available to the account

Enumerated Values

Parameter	Value
plan	free
plan	basic
plan	enterprise

Example responses

201 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "name": "Example Account",
  "plan": "free",
  "marketSlots": 10,
  "Companies": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
    }
  ],
  "Users": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "name": "Example User"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
201	Created	successful operation	Account
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to create accounts	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Get a list of accounts

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/accounts \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/accounts',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/accounts', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.geohub.app/v1/accounts', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.geohub.app/v1/accounts',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/accounts", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/accounts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /accounts

Gets a list of accounts for this user

Example responses

200 Response

[
  {
    "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
    "name": "Example Account",
    "plan": "free",
    "marketSlots": 10,
    "Companies": [
      {
        "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
      }
    ],
    "Users": [
      {
        "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
        "name": "Example User"
      }
    ]
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Inline
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to get accounts	None
404	Not Found	account not found	None
405	Method Not Allowed	method not allowed - invalid request method	None

Response Schema

Status Code 200

Array of Account objects

Name	Type	Required	Restrictions	Description
anonymous	[Account]	false	none	Array of Account objects
» uuid	string	false	none	A unique UUID for this account
» name	string	false	none	The account name
» plan	string	false	none	The plan of the account
» marketSlots	integer	false	none	The number of market slots available to the account
» Companies	[CompanySummary]	false	none	The companies associated with the account
»» uuid	string	false	none	A unique UUID for this company
» Users	[UserSummary]	false	none	The users associated with the account
»» uuid	string	false	none	A unique UUID for this user
»» name	string	false	none	The name of the user

Enumerated Values

Property	Value
plan	free
plan	basic
plan	enterprise

Delete an account

Code samples

# You can also use wget
curl -X DELETE https://api.geohub.app/v1/accounts/{accountUUID} \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/accounts/{accountUUID}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.geohub.app/v1/accounts/{accountUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.geohub.app/v1/accounts/{accountUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.geohub.app/v1/accounts/{accountUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.geohub.app/v1/accounts/{accountUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/accounts/{accountUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

DELETE /accounts/{accountUUID}

Delete an account.

Parameters

Name	In	Type	Required	Description
accountUUID	path	string	true	The unique UUID for this account

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Bad request - invalid UUID format	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to delete accounts	None
404	Not Found	account not found	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Update an account

Code samples

# You can also use wget
curl -X PUT https://api.geohub.app/v1/accounts/{accountUUID} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "name": "string",
  "plan": "string",
  "marketSlots": 0
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/accounts/{accountUUID}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.geohub.app/v1/accounts/{accountUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api.geohub.app/v1/accounts/{accountUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://api.geohub.app/v1/accounts/{accountUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.geohub.app/v1/accounts/{accountUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/accounts/{accountUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /accounts/{accountUUID}

Updates an existing account

Body parameter

{
  "name": "string",
  "plan": "string",
  "marketSlots": 0
}

Parameters

Name	In	Type	Required	Description
accountUUID	path	string	true	The unique UUID for this account
name	body	string	false	The name of the account
plan	body	string	false	The plan of the account
marketSlots	body	integer	false	The number of market slots available to the account

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "name": "Example Account",
  "plan": "free",
  "marketSlots": 10,
  "Companies": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
    }
  ],
  "Users": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "name": "Example User"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Account
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to update this company	None
404	Not Found	not found - account not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Companies

The /companies endpoints handle creating, getting and deleting companies for an account. Only account admins can create and delete companies.

Create company

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/companies \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "name": "Example Company",
  "website": "https://example.com",
  "accountUUID": "02958d31-409a-4491-9105-479f48b3c5ca"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/companies',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/companies', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/companies', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/companies',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/companies", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/companies");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /companies

Creates a new company

Body parameter

{
  "name": "Example Company",
  "website": "https://example.com",
  "accountUUID": "02958d31-409a-4491-9105-479f48b3c5ca"
}

Parameters

Name	In	Type	Required	Description
body	body	CompanyCreate	true	none
name	body	string	true	The name of the company
website	body	string	true	The website of the company
accountUUID	body	string	false	The UUID of the account - if admin user

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "name": "Example Company",
  "website": "https://example.com",
  "logoUrl": "https://example.com/logo.png",
  "companyProfile": {
    "name": "Example Company",
    "website": "https://example.com"
  },
  "marketCount": 10,
  "runCount": 10
}

Responses

Status	Meaning	Description	Schema
200	OK	Company created successfully	Company
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Get companies

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/companies \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/companies',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/companies', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.geohub.app/v1/companies', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.geohub.app/v1/companies',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/companies", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/companies");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /companies

Gets all companies for this account

Example responses

200 Response

[
  {
    "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
    "name": "Example Company",
    "website": "https://example.com",
    "logoUrl": "https://example.com/logo.png",
    "companyProfile": {
      "name": "Example Company",
      "website": "https://example.com"
    },
    "marketCount": 10,
    "runCount": 10
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Inline
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None

Response Schema

Status Code 200

An array of companies

Name	Type	Required	Restrictions	Description
anonymous	[Company]	false	none	An array of companies
» uuid	string	false	none	A unique UUID for this company
» name	string	false	none	The name of the company
» website	string	false	none	The website of the company
» logoUrl	string	false	none	The logo URL of the company
» companyProfile	object	false	none	The company profile
» marketCount	integer	false	none	The number of markets for this company
» runCount	integer	false	none	The number of runs for this company

Create market

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/companies/:companyUUID/markets \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/companies/:companyUUID/markets',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/companies/:companyUUID/markets', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/companies/:companyUUID/markets', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/companies/:companyUUID/markets',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/companies/:companyUUID/markets", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/companies/:companyUUID/markets");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /companies/:companyUUID/markets

Creates a new market

Body parameter

{
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney"
}

Parameters

Name	In	Type	Required	Description
body	body	MarketCreate	true	none
languageTag	body	string	true	The language tag of the market
country	body	string	true	The country of the market
city	body	string	false	The city of the market

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "personas": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "personaId": 1,
      "name": "Example Persona",
      "name_en": "Example Persona",
      "Questions": [
        {
          "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
          "content": {},
          "Evaluations": [
            {
              "content": {},
              "Citations": [
                {
                  "content": {}
                }
              ],
              "Sources": [
                {
                  "content": {}
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "intents": [
    {}
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Market created successfully	Market
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Delete a company

Code samples

# You can also use wget
curl -X DELETE https://api.geohub.app/v1/companies/{companyUUID} \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/companies/{companyUUID}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.geohub.app/v1/companies/{companyUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.geohub.app/v1/companies/{companyUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.geohub.app/v1/companies/{companyUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.geohub.app/v1/companies/{companyUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/companies/{companyUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

DELETE /companies/{companyUUID}

Delete a company.

Parameters

Name	In	Type	Required	Description
companyUUID	path	string	true	The unique UUID for this company

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Bad request - invalid UUID format	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
404	Not Found	company not found	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Update a company

Code samples

# You can also use wget
curl -X PUT https://api.geohub.app/v1/companies/{companyUUID} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "name": "string",
  "website": "string",
  "logoUrl": "string",
  "companyProfile": {}
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/companies/{companyUUID}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.geohub.app/v1/companies/{companyUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api.geohub.app/v1/companies/{companyUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://api.geohub.app/v1/companies/{companyUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.geohub.app/v1/companies/{companyUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/companies/{companyUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /companies/{companyUUID}

Updates an existing company

Body parameter

{
  "name": "string",
  "website": "string",
  "logoUrl": "string",
  "companyProfile": {}
}

Parameters

Name	In	Type	Required	Description
companyUUID	path	string	true	The unique UUID for this company
name	body	string	false	The name of the company
website	body	string	false	The website of the company
logoUrl	body	string	false	The logo URL of the company
companyProfile	body	object	false	The company profile

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "name": "Example Company",
  "website": "https://example.com",
  "logoUrl": "https://example.com/logo.png",
  "companyProfile": {
    "name": "Example Company",
    "website": "https://example.com"
  },
  "marketCount": 10,
  "runCount": 10
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Company
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to update this company	None
404	Not Found	not found - company not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Markets

The /markets endpoints handle creating, getting and deleting markets for a company. Only account admins can create and delete markets.

Take action on market

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/markets/{marketUUID}/actions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "action": "recreatePersonas, recreateQuestions"
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/markets/{marketUUID}/actions',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/markets/{marketUUID}/actions', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/markets/{marketUUID}/actions', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/markets/{marketUUID}/actions',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/markets/{marketUUID}/actions", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/markets/{marketUUID}/actions");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /markets/{marketUUID}/actions

Take action on a market

Body parameter

{
  "action": "recreatePersonas, recreateQuestions"
}

Parameters

Name	In	Type	Required	Description
body	body	MarketAction	true	none
action	body	string	true	The action to take on the market

Responses

Status	Meaning	Description	Schema
204	No Content	Market action taken successfully	None
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
404	Not Found	market not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Get market

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/markets/{marketUUID} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/markets/{marketUUID}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/markets/{marketUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.geohub.app/v1/markets/{marketUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.geohub.app/v1/markets/{marketUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/markets/{marketUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/markets/{marketUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /markets/{marketUUID}

Gets a market by UUID

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "personas": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "personaId": 1,
      "name": "Example Persona",
      "name_en": "Example Persona",
      "Questions": [
        {
          "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
          "content": {},
          "Evaluations": [
            {
              "content": {},
              "Citations": [
                {
                  "content": {}
                }
              ],
              "Sources": [
                {
                  "content": {}
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "intents": [
    {}
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Market
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None

Delete a market

Code samples

# You can also use wget
curl -X DELETE https://api.geohub.app/v1/markets/{marketUUID} \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/markets/{marketUUID}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.geohub.app/v1/markets/{marketUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.geohub.app/v1/markets/{marketUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.geohub.app/v1/markets/{marketUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.geohub.app/v1/markets/{marketUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/markets/{marketUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

DELETE /markets/{marketUUID}

Delete a market.

Parameters

Name	In	Type	Required	Description
marketUUID	path	string	true	The unique UUID for this market

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Bad request - invalid UUID format	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
404	Not Found	market not found	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Update a market

Code samples

# You can also use wget
curl -X PUT https://api.geohub.app/v1/markets/{marketUUID} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "languageTag": "string",
  "country": "string",
  "city": "string",
  "personas": [],
  "intents": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/markets/{marketUUID}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.geohub.app/v1/markets/{marketUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api.geohub.app/v1/markets/{marketUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://api.geohub.app/v1/markets/{marketUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.geohub.app/v1/markets/{marketUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/markets/{marketUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /markets/{marketUUID}

Updates an existing market

Body parameter

{
  "languageTag": "string",
  "country": "string",
  "city": "string",
  "personas": [],
  "intents": []
}

Parameters

Name	In	Type	Required	Description
marketUUID	path	string	true	The unique UUID for this market
languageTag	body	string	false	The language tag of the market
country	body	string	false	The country of the market
city	body	string	false	The city of the market
personas	body	array	false	The personas for the market
intents	body	array	false	The intents for the market

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "personas": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "personaId": 1,
      "name": "Example Persona",
      "name_en": "Example Persona",
      "Questions": [
        {
          "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
          "content": {},
          "Evaluations": [
            {
              "content": {},
              "Citations": [
                {
                  "content": {}
                }
              ],
              "Sources": [
                {
                  "content": {}
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "intents": [
    {}
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Market
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to update this market	None
404	Not Found	not found - market not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Runs

The /runs endpoints handle creating, getting run status and cancelling runs.

A run is a single execution of the GeoHub system for a company and market.

Create run

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/runs \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "companyUUID": "02958d31-409a-4491-9105-479f48b3c5ca",
  "isBrandExplicit": true,
  "useCanonicalCompany": true,
  "useCanonicalMarket": true,
  "useCanonicalQuestions": true,
  "marketUUID": "02958d31-409a-4491-9105-479f48b3c5ca",
  "seedUrl": "https://example.com",
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "model": "gpt-4o",
  "temperature": 0.5
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/runs',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/runs', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/runs', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/runs',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/runs", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/runs");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /runs

Creates a new run request

Body parameter

{
  "companyUUID": "02958d31-409a-4491-9105-479f48b3c5ca",
  "isBrandExplicit": true,
  "useCanonicalCompany": true,
  "useCanonicalMarket": true,
  "useCanonicalQuestions": true,
  "marketUUID": "02958d31-409a-4491-9105-479f48b3c5ca",
  "seedUrl": "https://example.com",
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "model": "gpt-4o",
  "temperature": 0.5
}

Parameters

Name	In	Type	Required	Description
body	body	RunCreate	true	none
companyUUID	body	string	true	The UUID of the company
isBrandExplicit	body	boolean	true	Flag to indicate whether the brand is explicit
useCanonicalCompany	body	boolean	false	Flag to indicate whether using canonical company profile
useCanonicalMarket	body	boolean	false	Flag to indicate whether using canonical market profile
useCanonicalQuestions	body	boolean	false	Flag to indicate whether using canonical questions
marketUUID	body	string	false	The UUID of the market - when using canonical market or questions
seedUrl	body	string	false	The URL to assess
languageTag	body	string	false	The language tag of the market
country	body	string	false	The country of the market
city	body	string	false	The city of the market
model	body	string	false	The name of the model to use for the run
temperature	body	number	false	The temperature to use for the run

Example responses

202 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "seedUrl": "https://example.com",
  "status": "queued",
  "plannedCount": 100,
  "completedCount": 100,
  "failedCount": 100,
  "useCanonicalCompany": false,
  "useCanonicalMarket": false,
  "useCanonicalQuestions": false,
  "isBrandExplicit": true,
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "companyProfile": {},
  "personas": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "personaId": 1,
      "name": "Example Persona",
      "name_en": "Example Persona",
      "Questions": [
        {
          "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
          "content": {},
          "Evaluations": [
            {
              "content": {},
              "Citations": [
                {
                  "content": {}
                }
              ],
              "Sources": [
                {
                  "content": {}
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "intents": [],
  "coreData": {
    "coverage": 50,
    "ownSiteShare": 23.5,
    "sovByDomain": {
      "example.com": 23.5
    }
  },
  "additionalData": {
    "qaMetrics": {}
  },
  "Questions": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "content": {},
      "Evaluations": [
        {
          "content": {},
          "Citations": [
            {
              "content": {}
            }
          ],
          "Sources": [
            {
              "content": {}
            }
          ]
        }
      ]
    }
  ],
  "Company": {
    "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
  }
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Run queued successfully	Run
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None
409	Conflict	conflict - a queued or running run already exists for this company with this seedUrl, languageTag, country, and city	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Get run

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/runs/{runUUID} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/runs/{runUUID}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/runs/{runUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.geohub.app/v1/runs/{runUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.geohub.app/v1/runs/{runUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/runs/{runUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/runs/{runUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /runs/{runUUID}

Gets a specific run

Parameters

Name	In	Type	Required	Description
runUUID	path	string	true	The run UUID

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "seedUrl": "https://example.com",
  "status": "queued",
  "plannedCount": 100,
  "completedCount": 100,
  "failedCount": 100,
  "useCanonicalCompany": false,
  "useCanonicalMarket": false,
  "useCanonicalQuestions": false,
  "isBrandExplicit": true,
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "companyProfile": {},
  "personas": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "personaId": 1,
      "name": "Example Persona",
      "name_en": "Example Persona",
      "Questions": [
        {
          "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
          "content": {},
          "Evaluations": [
            {
              "content": {},
              "Citations": [
                {
                  "content": {}
                }
              ],
              "Sources": [
                {
                  "content": {}
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "intents": [],
  "coreData": {
    "coverage": 50,
    "ownSiteShare": 23.5,
    "sovByDomain": {
      "example.com": 23.5
    }
  },
  "additionalData": {
    "qaMetrics": {}
  },
  "Questions": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "content": {},
      "Evaluations": [
        {
          "content": {},
          "Citations": [
            {
              "content": {}
            }
          ],
          "Sources": [
            {
              "content": {}
            }
          ]
        }
      ]
    }
  ],
  "Company": {
    "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Run
400	Bad Request	Bad request - invalid UUID format or path parameters	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to view this run	None
404	Not Found	run not found	None
405	Method Not Allowed	method not allowed	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Cancel run

Code samples

# You can also use wget
curl -X DELETE https://api.geohub.app/v1/runs/{runUUID} \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/runs/{runUUID}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.geohub.app/v1/runs/{runUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.geohub.app/v1/runs/{runUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.geohub.app/v1/runs/{runUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.geohub.app/v1/runs/{runUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/runs/{runUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

DELETE /runs/{runUUID}

Cancels a run.

Parameters

Name	In	Type	Required	Description
runUUID	path	string	true	The unique UUID for this run

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Bad request - invalid UUID format	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
404	Not Found	company not found	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Scheduled Runs

The /scheduled-runs endpoints handle creating, getting and updating scheduled runs.

A scheduled run is a recurring execution of a run for a company and market.

Create scheduled run

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/scheduled-runs \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "isBrandExplicit": true,
  "model": "gpt-4o",
  "temperature": 0.5,
  "marketUUID": "02958d31-409a-4491-9105-479f48b3c5ca"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/scheduled-runs',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/scheduled-runs', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/scheduled-runs', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/scheduled-runs',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/scheduled-runs", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/scheduled-runs");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /scheduled-runs

Creates a new scheduled run

Body parameter

{
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "isBrandExplicit": true,
  "model": "gpt-4o",
  "temperature": 0.5,
  "marketUUID": "02958d31-409a-4491-9105-479f48b3c5ca"
}

Parameters

Name	In	Type	Required	Description
body	body	ScheduledRunCreate	true	none
frequency	body	enum	true	The frequency of the scheduled run
timeOfDayUTC	body	string	true	The time of day of the scheduled run in UTC
dayOfWeek	body	integer	false	The day of the week of the scheduled run
dayOfMonth	body	integer	false	The day of the month of the scheduled run
isBrandExplicit	body	boolean	true	Whether the run is brand explicit
model	body	string	false	The name of the model to use for the run
temperature	body	number	false	The temperature to use for the run
marketUUID	body	string	true	The UUID of the market

Enumerated Values

Parameter	Value
frequency	daily
frequency	weekly
frequency	monthly

Example responses

201 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "nextRunDateTime": "2021-01-01T00:00:00.000Z",
  "isBrandExplicit": true,
  "llmSettings": {},
  "scheduledRunExecutionCount": 1
}

Responses

Status	Meaning	Description	Schema
201	Created	Scheduled run created successfully	ScheduledRun
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
404	Not Found	market not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
409	Conflict	conflict - a scheduled run already exists for this market	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Get scheduled runs

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/scheduled-runs \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/scheduled-runs',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/scheduled-runs', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.geohub.app/v1/scheduled-runs', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.geohub.app/v1/scheduled-runs',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/scheduled-runs", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/scheduled-runs");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /scheduled-runs

Gets all scheduled runs

Parameters

Name	In	Type	Required	Description
companyUUID	query	string	false	The UUID of the company

Example responses

200 Response

[
  {
    "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
    "frequency": "daily",
    "timeOfDayUTC": 720,
    "dayOfWeek": 1,
    "dayOfMonth": 1,
    "nextRunDateTime": "2021-01-01T00:00:00.000Z",
    "isBrandExplicit": true,
    "llmSettings": {},
    "scheduledRunExecutionCount": 1
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Inline
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None

Response Schema

Status Code 200

An array of scheduled runs

Name	Type	Required	Restrictions	Description
anonymous	[ScheduledRun]	false	none	An array of scheduled runs
» uuid	string	false	none	A unique UUID for this scheduled run
» frequency	string	false	none	The frequency of the scheduled run
» timeOfDayUTC	string	false	none	The time of day of the scheduled run in UTC
» dayOfWeek	integer	false	none	The day of the week of the scheduled run
» dayOfMonth	integer	false	none	The day of the month of the scheduled run
» nextRunDateTime	string	false	none	The next run date and time of the scheduled run
» isBrandExplicit	boolean	false	none	Whether the scheduled run is brand explicit
» llmSettings	object	false	none	The LLM settings for the scheduled run
» scheduledRunExecutionCount	integer	false	none	The number of scheduled run executions

Get scheduled run

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /scheduled-runs/{scheduledRunUUID}

Gets a scheduled run

Parameters

Name	In	Type	Required	Description
scheduledRunUUID	path	string	true	The UUID of the scheduled run

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "nextRunDateTime": "2021-01-01T00:00:00.000Z",
  "isBrandExplicit": true,
  "llmSettings": {},
  "ScheduledRunExecutions": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "status": "running",
      "attempt": 1,
      "errorMessage": "Error: Failed to execute scheduled run",
      "createdAt": "2021-01-01T00:00:00.000Z"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	ScheduledRunWithExecutions
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None

Update a scheduled run

Code samples

# You can also use wget
curl -X PUT https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "frequency": "string",
  "timeOfDayUTC": "string",
  "dayOfWeek": 0,
  "dayOfMonth": 0,
  "isBrandExplicit": true,
  "model": "string",
  "temperature": 0
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /scheduled-runs/{scheduledRunUUID}

Updates an existing scheduled run

Body parameter

{
  "frequency": "string",
  "timeOfDayUTC": "string",
  "dayOfWeek": 0,
  "dayOfMonth": 0,
  "isBrandExplicit": true,
  "model": "string",
  "temperature": 0
}

Parameters

Name	In	Type	Required	Description
scheduledRunUUID	path	string	true	The unique UUID for this scheduled run
frequency	body	string	false	The frequency of the scheduled run
timeOfDayUTC	body	string	false	The time of day of the scheduled run in UTC
dayOfWeek	body	integer	false	The day of the week of the scheduled run
dayOfMonth	body	integer	false	The day of the month of the scheduled run
isBrandExplicit	body	boolean	false	Whether the scheduled run is brand explicit
model	body	string	false	The model to use for the scheduled run
temperature	body	number	false	The temperature to use for the scheduled run

Example responses

200 Response

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "nextRunDateTime": "2021-01-01T00:00:00.000Z",
  "isBrandExplicit": true,
  "llmSettings": {},
  "scheduledRunExecutionCount": 1
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	ScheduledRun
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to update this scheduled run	None
404	Not Found	not found - scheduled run not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Delete a scheduled run

Code samples

# You can also use wget
curl -X DELETE https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID} \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/scheduled-runs/{scheduledRunUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

DELETE /scheduled-runs/{scheduledRunUUID}

Delete a scheduled run.

Parameters

Name	In	Type	Required	Description
scheduledRunUUID	path	string	true	The unique UUID for this scheduled run

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Bad request - invalid UUID format	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
404	Not Found	scheduled run not found	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Images

The /images endpoints handle creating images for a company. Only account admins can create images.

Create image

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/images \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "contentType": "image/jpeg",
  "prepend": "companies/1"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/images',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/images', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/images', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/images',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/images", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/images");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /images

Creates a new image

Body parameter

{
  "contentType": "image/jpeg",
  "prepend": "companies/1"
}

Parameters

Name	In	Type	Required	Description
contentType	body	string	true	The type of the image like image/jpeg, image/png, image/gif, etc.
prepend	body	string	false	The prepend to the image filename

Enumerated Values

Parameter	Value
contentType	image/jpeg
contentType	image/png
contentType	image/gif
contentType	etc.

Example responses

200 Response

{
  "imageFilename": "image.jpg",
  "presignedPutUrl": "https://example.com/image.jpg",
  "presignedGetUrl": "https://example.com/image.jpg"
}

Responses

Status	Meaning	Description	Schema
200	OK	Image created successfully	Image
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Stats

The /public-stats endpoint returns summary data and statistics about the usage of the GeoHub system.

This endpoint does not require authentication as it is publicly accessible and used on the public-facing website.

The endpoint only supports GET requests.

Get public stats

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/public-stats \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.geohub.app/v1/public-stats',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/public-stats', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.geohub.app/v1/public-stats', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.geohub.app/v1/public-stats',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/public-stats", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/public-stats");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /public-stats

Get public platform metrics

Returns public metrics

Example responses

200 Response

{
  "users": 0
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Inline
405	Method Not Allowed	Method not allowed	None
500	Internal Server Error	Internal server error	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» users	number(integer)	false	none	Overall users

Telemetry

The /telemetry endpoints handle receiving telemetry data from the GeoHub system.

This endpoint does not require authentication as it is publicly accessible and used on the public-facing website.

The endpoint only supports POST requests.

Create new telemetry event

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/telemetry/heartbeat \
  -H 'Content-Type: application/json'

const inputBody = '{
  "timeZone": "Europe/London",
  "locale": "en-GB",
  "route": "/dashboard"
}';
const headers = {
  'Content-Type':'application/json'
};

fetch('https://api.geohub.app/v1/telemetry/heartbeat',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/telemetry/heartbeat', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json'
}

r = requests.post('https://api.geohub.app/v1/telemetry/heartbeat', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
}

result = RestClient.post 'https://api.geohub.app/v1/telemetry/heartbeat',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/telemetry/heartbeat", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/telemetry/heartbeat");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /telemetry/heartbeat

Creates a new telemetry event.

Body parameter

{
  "timeZone": "Europe/London",
  "locale": "en-GB",
  "route": "/dashboard"
}

Parameters

Name	In	Type	Required	Description
timeZone	body	string	false	The user's time zone
locale	body	string	false	The user's locale
route	body	string	false	The user's route

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - invalid request body	None

Users

Create new user

Code samples

# You can also use wget
curl -X POST https://api.geohub.app/v1/users \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "name": "string",
  "role": "user",
  "email": "string",
  "accountUUID": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/users',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.geohub.app/v1/users', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.geohub.app/v1/users', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.geohub.app/v1/users',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.geohub.app/v1/users", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/users");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /users

Creates a new user.

Body parameter

{
  "name": "string",
  "role": "user",
  "email": "string",
  "accountUUID": "string"
}

Parameters

Name	In	Type	Required	Description
name	body	string	true	The name of the user
role	body	string	false	The role of the user. Admin users can set any role, accountAdmin users can only set accountAdmin or user roles.
email	body	string	true	The user's email
accountUUID	body	string	false	The account UUID. Required when admin users create accountAdmin or user users. Not required when creating admin users.

Enumerated Values

Parameter	Value
role	user
role	accountAdmin
role	admin

Example responses

201 Response

{
  "uuid": "string",
  "name": "string",
  "email": "user@example.com",
  "role": "user",
  "isMe": true,
  "Account": {
    "uuid": "string",
    "name": "string"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	successful operation	User
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to upload users to this account	None
404	Not Found	account not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
409	Conflict	conflict - email already in use	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Get users

Code samples

# You can also use wget
curl -X GET https://api.geohub.app/v1/users \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/users',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.geohub.app/v1/users', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.geohub.app/v1/users', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.geohub.app/v1/users',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.geohub.app/v1/users", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/users");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /users

Gets a list of users. If the user role is admin return all users. If the user role is accountAdmin return all users for the account.

Example responses

200 Response

[
  {
    "uuid": "string",
    "name": "string",
    "email": "user@example.com",
    "role": "user",
    "isMe": true,
    "Account": {
      "uuid": "string",
      "name": "string"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Inline
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - user not authorized to get users	None
404	Not Found	not found - user not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Response Schema

Status Code 200

Array of users

Name	Type	Required	Restrictions	Description
anonymous	[User]	false	none	Array of users
» uuid	string	false	none	The unique UUID for this user
» name	string	false	none	The name of the user
» email	string(email)	false	none	The email of the user
» role	string	false	none	The role of the user
» isMe	boolean	false	none	Whether the user is the current user
» Account	object	false	none	The account object
»» uuid	string	false	none	The unique UUID for this account
»» name	string	false	none	The name of the account

Enumerated Values

Property	Value
role	user
role	accountAdmin
role	admin

Update a user

Code samples

# You can also use wget
curl -X PUT https://api.geohub.app/v1/users/{uuid} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

const inputBody = '{
  "name": "string",
  "email": "user@example.com",
  "profileCountryCode": "string",
  "password": "stringst",
  "role": "user"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/users/{uuid}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.geohub.app/v1/users/{uuid}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api.geohub.app/v1/users/{uuid}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://api.geohub.app/v1/users/{uuid}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.geohub.app/v1/users/{uuid}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/users/{uuid}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /users/{uuid}

Updates an existing user

Body parameter

{
  "name": "string",
  "email": "user@example.com",
  "profileCountryCode": "string",
  "password": "stringst",
  "role": "user"
}

Parameters

Name	In	Type	Required	Description
uuid	path	string	true	The unique UUID for this user
name	body	string	false	The name of the user
email	body	string(email)	false	The email of the user
profileCountryCode	body	string	false	The profile country code of the user.
password	body	string	false	The password of the user. Can only be set by the user.
role	body	string	false	The role of the user. Admin users can set any role, accountAdmin users can only set accountAdmin or user roles.

Enumerated Values

Parameter	Value
role	user
role	accountAdmin
role	admin

Example responses

200 Response

{
  "uuid": "string",
  "name": "string",
  "email": "user@example.com",
  "role": "user",
  "isMe": true,
  "Account": {
    "uuid": "string",
    "name": "string"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	User
400	Bad Request	bad request - invalid request body	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
404	Not Found	not found - user not found	None
405	Method Not Allowed	method not allowed - invalid request method	None
409	Conflict	conflict - email already in use	None
422	Unprocessable Entity	unprocessable entity - check error message	None

Delete user

Code samples

# You can also use wget
curl -X DELETE https://api.geohub.app/v1/users/{uuid} \
  -H 'Authorization: Bearer {access-token}'


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.geohub.app/v1/users/{uuid}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.geohub.app/v1/users/{uuid}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.geohub.app/v1/users/{uuid}', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.geohub.app/v1/users/{uuid}',
  params: {
  }, headers: headers

p JSON.parse(result)

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.geohub.app/v1/users/{uuid}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

URL obj = new URL("https://api.geohub.app/v1/users/{uuid}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

DELETE /users/{uuid}

Delete a user

Parameters

Name	In	Type	Required	Description
uuid	path	string	true	The unique UUID for this user

Responses

Status	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	bad request - invalid path parameters	None
401	Unauthorized	unauthorised - invalid Authorisation token	None
403	Forbidden	forbidden - insufficient permissions	None
404	Not Found	user not found	None
405	Method Not Allowed	method not allowed - invalid request method	None

Schemas

Login

{
  "idToken": "02958d31-409a-4491-9105-479f48b3c5ca",
  "idTokenExpiry": 0,
  "name": "John Doe",
  "role": "user",
  "Companies": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "name": "Example Company",
      "website": "https://example.com",
      "logoUrl": "https://example.com/logo.png",
      "companyProfile": {
        "name": "Example Company",
        "website": "https://example.com"
      },
      "marketCount": 10,
      "runCount": 10
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
idToken	string	false	none	A unique idToken for this user login
idTokenExpiry	integer	false	none	The idToken expiry as a timestamp in seconds
name	string	false	none	The user's name
role	string	false	none	The user's role
Companies	[Company]	false	none	The companies associated with this account

Enumerated Values

Property	Value
role	user
role	accountAdmin
role	admin

Company

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "name": "Example Company",
  "website": "https://example.com",
  "logoUrl": "https://example.com/logo.png",
  "companyProfile": {
    "name": "Example Company",
    "website": "https://example.com"
  },
  "marketCount": 10,
  "runCount": 10
}

Company information. Returns the company.

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this company
name	string	false	none	The name of the company
website	string	false	none	The website of the company
logoUrl	string	false	none	The logo URL of the company
companyProfile	object	false	none	The company profile
marketCount	integer	false	none	The number of markets for this company
runCount	integer	false	none	The number of runs for this company

Account

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "name": "Example Account",
  "plan": "free",
  "marketSlots": 10,
  "Companies": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
    }
  ],
  "Users": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "name": "Example User"
    }
  ]
}

Account information. Returns the account.

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this account
name	string	false	none	The account name
plan	string	false	none	The plan of the account
marketSlots	integer	false	none	The number of market slots available to the account
Companies	[CompanySummary]	false	none	The companies associated with the account
Users	[UserSummary]	false	none	The users associated with the account

Enumerated Values

Property	Value
plan	free
plan	basic
plan	enterprise

UserSummary

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "name": "Example User"
}

User summary information

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this user
name	string	false	none	The name of the user

CompanySummary

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
}

A summary of a company

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this company

MarketSummary

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "languageTag": "en-AU",
  "country": "AU"
}

Market summary information

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this market
languageTag	string	false	none	The language tag of the market
country	string	false	none	The country of the market

RunSummary

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "seedUrl": "https://example.com",
  "status": "queued",
  "plannedCount": 100,
  "completedCount": 100,
  "failedCount": 100,
  "isBrandExplicit": true,
  "useCanonicalCompany": false,
  "useCanonicalMarket": false,
  "useCanonicalQuestions": false,
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "logoUrl": "https://example.com/logo.png",
  "coreData": {
    "coverageEither": 50,
    "ownSiteShare": 23.5,
    "topDomainsByRRF": [
      {
        "domain": "example.com",
        "sharePct": 23.5
      }
    ]
  },
  "createdAt": "2021-01-01T00:00:00.000Z"
}

A run

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this run
seedUrl	string	false	none	The seed URL for the run
status	string	false	none	The status of the run
plannedCount	integer	false	none	The planned count for the run
completedCount	integer	false	none	The completed count for the run
failedCount	integer	false	none	The failed count for the run
isBrandExplicit	boolean	false	none	Whether the run is brand explicit
useCanonicalCompany	boolean	false	none	Whether the company profile was used for the run
useCanonicalMarket	boolean	false	none	Whether the company profile was used for the run
useCanonicalQuestions	boolean	false	none	Whether the questions were used for the run
languageTag	string	false	none	The language tag for the run
country	string	false	none	The country for the run
city	string	false	none	The city for the run
logoUrl	string	false	none	The logo URL for the run
coreData	object	false	none	The core data for the run - provided as a summary of the coreData field
createdAt	string	false	none	The creation date and time for the run

CompanyCreate

{
  "name": "Example Company",
  "website": "https://example.com",
  "accountUUID": "02958d31-409a-4491-9105-479f48b3c5ca"
}

Company creation request

Properties

Name	Type	Required	Restrictions	Description
name	string	true	none	The name of the company
website	string	true	none	The website of the company
accountUUID	string	false	none	The UUID of the account - if admin user

MarketCreate

{
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney"
}

Market creation request

Properties

Name	Type	Required	Restrictions	Description
languageTag	string	true	none	The language tag of the market
country	string	true	none	The country of the market
city	string	false	none	The city of the market

Market

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "personas": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "personaId": 1,
      "name": "Example Persona",
      "name_en": "Example Persona",
      "Questions": [
        {
          "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
          "content": {},
          "Evaluations": [
            {
              "content": {},
              "Citations": [
                {
                  "content": {}
                }
              ],
              "Sources": [
                {
                  "content": {}
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "intents": [
    {}
  ]
}

Market information

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this market
languageTag	string	false	none	The language tag of the market
country	string	false	none	The country of the market
city	string	false	none	The city of the market
personas	[Persona]	false	none	The personas for this market
intents	[Intent]	false	none	The intents for this market

Persona

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "personaId": 1,
  "name": "Example Persona",
  "name_en": "Example Persona",
  "Questions": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "content": {},
      "Evaluations": [
        {
          "content": {},
          "Citations": [
            {
              "content": {}
            }
          ],
          "Sources": [
            {
              "content": {}
            }
          ]
        }
      ]
    }
  ]
}

A persona for this run

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this persona
personaId	integer	false	none	The persona ID for this persona
name	string	false	none	The name of the persona
name_en	string	false	none	The name of the persona in English
Questions	[Question]	false	none	The questions for this persona

Question

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "content": {},
  "Evaluations": [
    {
      "content": {},
      "Citations": [
        {
          "content": {}
        }
      ],
      "Sources": [
        {
          "content": {}
        }
      ]
    }
  ]
}

A question for this run

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this question
content	object	false	none	The question content
Evaluations	[Evaluation]	false	none	The evaluations for this question

Intent

{}

A customer intent for the market

Properties

None

MarketAction

{
  "action": "recreatePersonas, recreateQuestions"
}

Market action

Properties

Name	Type	Required	Restrictions	Description
action	string	true	none	The action to take on the market

RunCreate

{
  "companyUUID": "02958d31-409a-4491-9105-479f48b3c5ca",
  "isBrandExplicit": true,
  "useCanonicalCompany": true,
  "useCanonicalMarket": true,
  "useCanonicalQuestions": true,
  "marketUUID": "02958d31-409a-4491-9105-479f48b3c5ca",
  "seedUrl": "https://example.com",
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "model": "gpt-4o",
  "temperature": 0.5
}

Run creation request

Properties

Name	Type	Required	Restrictions	Description
companyUUID	string	true	none	The UUID of the company
isBrandExplicit	boolean	true	none	Flag to indicate whether the brand is explicit
useCanonicalCompany	boolean	false	none	Flag to indicate whether using canonical company profile
useCanonicalMarket	boolean	false	none	Flag to indicate whether using canonical market profile
useCanonicalQuestions	boolean	false	none	Flag to indicate whether using canonical questions
marketUUID	string	false	none	The UUID of the market - when using canonical market or questions
seedUrl	string	false	none	The URL to assess
languageTag	string	false	none	The language tag of the market
country	string	false	none	The country of the market
city	string	false	none	The city of the market
model	string	false	none	The name of the model to use for the run
temperature	number	false	none	The temperature to use for the run

Run

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "seedUrl": "https://example.com",
  "status": "queued",
  "plannedCount": 100,
  "completedCount": 100,
  "failedCount": 100,
  "useCanonicalCompany": false,
  "useCanonicalMarket": false,
  "useCanonicalQuestions": false,
  "isBrandExplicit": true,
  "languageTag": "en-AU",
  "country": "AU",
  "city": "Sydney",
  "companyProfile": {},
  "personas": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "personaId": 1,
      "name": "Example Persona",
      "name_en": "Example Persona",
      "Questions": [
        {
          "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
          "content": {},
          "Evaluations": [
            {
              "content": {},
              "Citations": [
                {
                  "content": {}
                }
              ],
              "Sources": [
                {
                  "content": {}
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "intents": [],
  "coreData": {
    "coverage": 50,
    "ownSiteShare": 23.5,
    "sovByDomain": {
      "example.com": 23.5
    }
  },
  "additionalData": {
    "qaMetrics": {}
  },
  "Questions": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "content": {},
      "Evaluations": [
        {
          "content": {},
          "Citations": [
            {
              "content": {}
            }
          ],
          "Sources": [
            {
              "content": {}
            }
          ]
        }
      ]
    }
  ],
  "Company": {
    "uuid": "02958d31-409a-4491-9105-479f48b3c5ca"
  }
}

Run information. Returns the run.

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this run
seedUrl	string	false	none	The seed URL for this run
status	string	false	none	The run status
plannedCount	integer	false	none	The planned task count for this run
completedCount	integer	false	none	The completed task count for this run
failedCount	integer	false	none	The failed task count for this run
useCanonicalCompany	boolean	false	none	Whether the run is using the canonical company profile
useCanonicalMarket	boolean	false	none	Whether the run is using the canonical company profile
useCanonicalQuestions	boolean	false	none	Whether the run is using the canonical questions
isBrandExplicit	boolean	false	none	Whether the question is brand explicit
languageTag	string	false	none	The language tag for this run
country	string	false	none	The country for this run
city	string	false	none	The city for this run
companyProfile	object	false	none	The company profile for this run
personas	[Persona]	false	none	The personas for this run
intents	array	false	none	The intents for this run
coreData	object	false	none	The core data for this run
additionalData	object	false	none	Additional data including QA metrics and variance
Questions	[Question]	false	none	The questions for this run
Company	CompanySummary	false	none	The company summary for this run

Evaluation

{
  "content": {},
  "Citations": [
    {
      "content": {}
    }
  ],
  "Sources": [
    {
      "content": {}
    }
  ]
}

An evaluation for this question

Properties

Name	Type	Required	Restrictions	Description
content	object	false	none	The evaluation for this question
Citations	[Citation]	false	none	The citations for this evaluation
Sources	[Source]	false	none	The sources for this evaluation

Citation

{
  "content": {}
}

A citation for this evaluation

Properties

Name	Type	Required	Restrictions	Description
content	object	false	none	The citation for this evaluation

Source

{
  "content": {}
}

Web search queries and sources for this evaluation from the web_search_call results (if available)

Properties

Name	Type	Required	Restrictions	Description
content	object	false	none	The queries and sources for this evaluation

ScheduledRunCreate

{
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "isBrandExplicit": true,
  "model": "gpt-4o",
  "temperature": 0.5,
  "marketUUID": "02958d31-409a-4491-9105-479f48b3c5ca"
}

Scheduled run creation request

Properties

Name	Type	Required	Restrictions	Description
frequency	enum	true	none	The frequency of the scheduled run
timeOfDayUTC	string	true	none	The time of day of the scheduled run in UTC
dayOfWeek	integer	false	none	The day of the week of the scheduled run
dayOfMonth	integer	false	none	The day of the month of the scheduled run
isBrandExplicit	boolean	true	none	Whether the run is brand explicit
model	string	false	none	The name of the model to use for the run
temperature	number	false	none	The temperature to use for the run
marketUUID	string	true	none	The UUID of the market

Enumerated Values

Property	Value
frequency	daily
frequency	weekly
frequency	monthly

ScheduledRun

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "nextRunDateTime": "2021-01-01T00:00:00.000Z",
  "isBrandExplicit": true,
  "llmSettings": {},
  "scheduledRunExecutionCount": 1
}

Scheduled run information

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this scheduled run
frequency	string	false	none	The frequency of the scheduled run
timeOfDayUTC	string	false	none	The time of day of the scheduled run in UTC
dayOfWeek	integer	false	none	The day of the week of the scheduled run
dayOfMonth	integer	false	none	The day of the month of the scheduled run
nextRunDateTime	string	false	none	The next run date and time of the scheduled run
isBrandExplicit	boolean	false	none	Whether the scheduled run is brand explicit
llmSettings	object	false	none	The LLM settings for the scheduled run
scheduledRunExecutionCount	integer	false	none	The number of scheduled run executions

ScheduledRunWithExecutions

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "frequency": "daily",
  "timeOfDayUTC": 720,
  "dayOfWeek": 1,
  "dayOfMonth": 1,
  "nextRunDateTime": "2021-01-01T00:00:00.000Z",
  "isBrandExplicit": true,
  "llmSettings": {},
  "ScheduledRunExecutions": [
    {
      "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
      "status": "running",
      "attempt": 1,
      "errorMessage": "Error: Failed to execute scheduled run",
      "createdAt": "2021-01-01T00:00:00.000Z"
    }
  ]
}

Scheduled run information with executions

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this scheduled run
frequency	string	false	none	The frequency of the scheduled run
timeOfDayUTC	string	false	none	The time of day of the scheduled run in UTC
dayOfWeek	integer	false	none	The day of the week of the scheduled run
dayOfMonth	integer	false	none	The day of the month of the scheduled run
nextRunDateTime	string	false	none	The next run date and time of the scheduled run
isBrandExplicit	boolean	false	none	Whether the scheduled run is brand explicit
llmSettings	object	false	none	The LLM settings for the scheduled run
ScheduledRunExecutions	[ScheduledRunExecution]	false	none	The scheduled run executions

ScheduledRunExecution

{
  "uuid": "02958d31-409a-4491-9105-479f48b3c5ca",
  "status": "running",
  "attempt": 1,
  "errorMessage": "Error: Failed to execute scheduled run",
  "createdAt": "2021-01-01T00:00:00.000Z"
}

A scheduled run execution

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	A unique UUID for this scheduled run execution
status	string	false	none	The status of the scheduled run execution
attempt	integer	false	none	The attempt number of the scheduled run execution
errorMessage	string	false	none	The error message of the scheduled run execution
createdAt	string	false	none	The date and time the scheduled run execution was created

User

{
  "uuid": "string",
  "name": "string",
  "email": "user@example.com",
  "role": "user",
  "isMe": true,
  "Account": {
    "uuid": "string",
    "name": "string"
  }
}

A user object

Properties

Name	Type	Required	Restrictions	Description
uuid	string	false	none	The unique UUID for this user
name	string	false	none	The name of the user
email	string(email)	false	none	The email of the user
role	string	false	none	The role of the user
isMe	boolean	false	none	Whether the user is the current user
Account	object	false	none	The account object
» uuid	string	false	none	The unique UUID for this account
» name	string	false	none	The name of the account

Enumerated Values

Property	Value
role	user
role	accountAdmin
role	admin

Image

{
  "imageFilename": "image.jpg",
  "presignedPutUrl": "https://example.com/image.jpg",
  "presignedGetUrl": "https://example.com/image.jpg"
}

Image information

Properties

Name	Type	Required	Restrictions	Description
imageFilename	string	false	none	The filename of the image in the S3 bucket
presignedPutUrl	string	false	none	The presigned URL for the image upload
presignedGetUrl	string	false	none	The presigned URL for the image retrieval

GeoHub API v1.0.0

Authentication

Auth

Create new login

Parameters

Responses

Request password reset

Parameters

Responses

Complete password reset

Parameters

Responses

Accounts

Create new account

Parameters

Enumerated Values

Responses

Get a list of accounts

Responses

Response Schema

Enumerated Values

Delete an account

Parameters

Responses

Update an account

Parameters

Responses

Companies

Create company

Parameters

Responses

Get companies

Responses

Response Schema

Create market

Parameters

Responses

Delete a company

Parameters

Responses

Update a company

Parameters

Responses

Markets

Take action on market

Parameters

Responses

Get market

Responses

Delete a market

Parameters

Responses

Update a market

Parameters

Responses

Runs

Create run

Parameters

Responses

Get run

Parameters

Responses

Cancel run

Parameters

Responses

Scheduled Runs

Create scheduled run

Parameters

Enumerated Values

Responses

Get scheduled runs

Parameters

Responses

Response Schema

Get scheduled run

Parameters

Responses

Update a scheduled run

Parameters

Responses