howloud logo
API docs by Redocly

Howloud (2.0.0)

Download OpenAPI specification:

URL: https://www.howloud.com

Introduction

The howloud API offers map tiles and soundscores.

Retrieves a soundscore for the given latitude and longitude

Authorizations:
query-api-keyheader-api-key
query Parameters
lat
number
Example: lat=37.13397

latitude

lng
number
Example: lng=-93.32604

longitude

Responses

Request samples 

params = { 'lng': '-93.3', 'lat': '37.12' }
url = 'https://api.howloud.com/v2/score'
headers = {'x-api-key': '<YOUR API KEY>'}
r = requests.get(url, params=params, headers=headers)
res = r.json()
print(res['result'][0]['score'])

Response samples

Content type
application/json
{
  • "status": "OK",
  • "request": {
    },
  • "result": {
    }
}

Retrieves up to 250 soundscores for the given coordinates

Submit a list of locations to get soundscore results in a single request. Each input object must have:

  • id: a user-supplied string (not validated or used by the system, but must be a string)
  • lat: latitude (number)
  • lng: longitude (number)

The response will be a list of objects, each containing:

  • id, lat, lng (echoed from input)
  • result: the same as the result member from GET /v2/score

This endpoint is suitable for synchronous scoring of a small number of locations.

For larger requests use the /v2/jobs endpoints for asynchronous processing of up to 10,000 locations.

Request Body schema: application/json
required
Array
id
required
string
lat
required
number
lng
required
number

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves tiles for the given type, latitude, longitude and zoom level (WGS84/EPSG:3857)

Authorizations:
query-api-keyheader-api-key
path Parameters
type
required
string
Enum: "airports" "local" "score" "traffic"
Example: airports

type of tile to retrieve

z
required
integer
Example: 14

z coordinate of the tile (wgs84)

x
required
integer
Example: 2622

x coordinate of the tile (wgs84)

y
required
integer
Example: 5719

y coordinate of the tile (wgs84)

Responses

Request samples 

url = 'https://api.howloud.com/v2/tiles/airports/12/1195/1565.png'
headers = {'x-api-key': '<YOUR API KEY>'}
r = requests.get(url, params=params, headers=headers)

Retrieves soundscore heatmap, an html map showing soundscore heatmap tiles. Requires trailing slash.

Authorizations:
query-api-keyheader-api-key

Responses

Request samples 

https://api.howloud.com/map/?x-api-key=<YOUR API KEY>

Retrieves soundscore coverage, an html map showing soundscore coverage. Requires trailing slash.

Authorizations:
query-api-keyheader-api-key

Responses

Request samples 

https://api.howloud.com/coverage/?x-api-key=<YOUR API KEY>

Create a new job and get a presigned S3 upload URL

Create a new job to process a bulk upload of up to 10,000 locations. The response includes a presigned S3 upload URL where the user can upload a file containing the locations to be processed.

Limit: The uploaded NDJSON file may contain up to 10,000 records. Larger uploads will be rejected.

Upload Format: The file uploaded to the S3 presigned URL MUST be in newline-delimited JSON (NDJSON) format. Each line should be a valid JSON object with the following structure:

{ "id": <string>, "lat": <number>, "lng": <number> }

  • The id field is a user-supplied string. It is not used or validated by the system, but must be a string. You can use this field to correlate results with your original request after retrieving results from S3.

Example NDJSON file:

{ "id": "abc123", "lat": 37.12, "lng": -93.3 }
{ "id": "def456", "lat": 37.13, "lng": -93.4 }

After uploading the file to the provided URL, the job will be processed asynchronously. Users can check the status of the job using the job ID returned in the response.

Authorizations:
query-api-keyheader-api-key

Responses

Request samples 

import requests
url = 'https://api.howloud.com/v2/jobs'
headers = {'x-api-key': '<YOUR API KEY>'}
r = requests.post(url, headers=headers)
job = r.json()
print(job)
uploadUrl = job['uploadUrl']

# Prepare NDJSON file
with open('locations.ndjson', 'w') as f:
    f.write('{"id": "abc123", "lat": 37.12, "lng": -93.3 }\n')
    f.write('{"id": "def456", "lat": 37.13, "lng": -93.4 }\n')
# Example PUT to S3
with open('locations.ndjson', 'rb') as f:
    put_resp = requests.put(uploadUrl, data=f, headers={"Content-Type": "application/x-ndjson"})
    print(put_resp.status_code)

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "uploadUrl": "string",
  • "status": "waiting_for_upload"
}

Get job status and details

Retrieve the status and details of a bulk job. If the job is completed, the response will include a presigned S3 download URL (downloadUrl).

How to use:

  1. Call this endpoint with the job ID to check the job status.
  2. If the job status is completed and a downloadUrl is present, use the presigned URL to download your results file.

The downloaded file will be in NDJSON format, with each line containing a JSON object like: { "id": <string>, "lat": <number>, "lng": <number>, "result": <same as the JSON for GET /score> }

  • The id field is a user-supplied string from your original request. It is not used or validated by the system, but must be a string. Use this field to correlate each result with your input data.

Example NDJSON result file:

{ "id": "abc123", "lat": 37.12, "lng": -93.3, "result": { "score": 80, ... } }
{ "id": "def456", "lat": 37.13, "lng": -93.4, "result": { "score": 75, ... } }

Download the file using curl or Python as shown in the examples below.

path Parameters
jobId
required
string

Responses

Request samples 

import requests
job_id = '<jobId>'
url = f'https://api.howloud.com/v2/jobs/{job_id}'
headers = {'x-api-key': '<YOUR API KEY>'}
r = requests.get(url, headers=headers)
job = r.json()
print(job)
if job.get('status') == 'completed' and 'downloadUrl' in job:
    # Download result
    result = requests.get(job['downloadUrl'])
    with open('result.dat', 'wb') as f:
        f.write(result.content)

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "status": "string",
  • "createdAt": 0,
  • "updatedAt": 0,
  • "error": "string",
  • "processedCount": 0,
  • "totalCount": 0,
  • "downloadUrl": "string"
}