Create a Saved Location

Create a new Saved Location to begin seeing insights.

Create a Saved Location

post

Create a new Saved Location. The recommended approach is to provide only origin_geojson (a GeoJSON Point at the exact location of the business) together with an industry value, without specifying geojson. PredictHQ will automatically calculate and store a Predicted Impact Area in the geojson field, calibrated for the business type.

Only specify geojson directly if you need a custom area rather than the auto-calculated Predicted Impact Area. Use place_ids instead of geojson when the location represents an entire city, state, or country.

Returns a location_id that can be reused across the Events, Features, and Beam APIs without re-supplying coordinates.

Authorizations

BearerAuth

AuthorizationstringRequired

Enter your PredictHQ API key. The Bearer prefix is added automatically.

When calling the API directly, send: Authorization: Bearer <YOUR_API_KEY> as documented at https://docs.predicthq.com/api/overview/authenticating

Body

application/json

The request body for creating a new Saved Location. Provide location geometry via origin_geojson (recommended), geojson, or place_ids.

location_codestringOptional

An optional identifier for your location.

The intention here is to use your own identifier for the location if you have one. E.g., you might have stores/hotels/etc in your system with their own ID

• use that ID here to make it easier to lookup the location later.

namestringOptional

Name of the Saved Location.

E.g. My Location

Example: My Location

descriptionstringOptional

Description of the location.

labelsstring[]Optional

A list of labels to help you categorize your locations. You can use these labels to search upon.

E.g.

  {
    "labels": ["label1", "label2"]
  }

Example: test

place_idsinteger[]Optional

You can define the geolocation of the Saved Location either by GeoJSON or Place IDs.

The Place IDs option is typically used when the location covers an entire city, county, state or country.

Use our Places API to search for the correct Place ID.

formatted_addressstringOptional

The street address of the location.

industrystring · enumOptional

The industry of your business. This is used to calculate the Impact Area for your location when you specify the origin_geojson field.

Possible values:

Responses

201

Location created successfully

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

post

/v1/saved-locations

HTTPcURLJavaScriptPython

POST /v1/saved-locations HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 409

{
  "location_code": "text",
  "name": "My Location",
  "description": "text",
  "labels": "test",
  "geojson": {
    "type": "Feature",
    "properties": {
      "radius": 3.17,
      "radius_unit": "mi"
    },
    "geometry": {
      "type": "Point",
      "coordinates": [
        -122.3816274,
        37.61911449999999
      ]
    }
  },
  "place_ids": [
    1
  ],
  "formatted_address": "text",
  "industry": "parking",
  "origin_geojson": {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [
        -122.3816274,
        37.61911449999999
      ]
    }
  }
}

{
  "location_id": "text"
}

Examples

Create Using Point and Radius

curl

curl --location 'https://api.predicthq.com/v1/saved-locations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "name": "Example of creating a saved location",
    "geojson": {
        "type": "Feature",
        "properties": {
            "radius": 2.23,
            "radius_unit": "mi"
        },
        "geometry": {
            "type": "Point",
            "coordinates": [
                -115.1728484,
                36.1147065
            ]
        }
    }
}'

python

Create Using Place ID

curl

curl --location 'https://api.predicthq.com/v1/saved-locations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "name": "Test with place_id",
    "place_ids": [ 2750405 ]
}'

python

OpenAPI Spec

The OpenAPI spec for Saved Locations API can be found here.

Guides

Below are some guides relevant to this API:

• Working with Location-Based Subscriptions