Complete reference guide for all AWS Location Services v2 APIs available through Ours Privacy Advanced Location Services.

Location APIs Reference

Ours Privacy Advanced Location Services provides access to AWS Location Services v2 APIs through our HIPAA-compliant infrastructure. This reference covers all available location APIs, including endpoints, request formats, and examples.

Base Endpoint

All location APIs are accessed through:

https://cdn.oursprivacy.com/location-services

Custom Domain Support

If you're using a custom domain, replace cdn.oursprivacy.com with your custom domain:

https://metrics.yourdomain.com/location-services

Authentication

All API requests require authentication using the key query parameter:

?key=YOUR-API-KEY-HERE

Replace YOUR-API-KEY-HERE with your API key from the Ours Privacy dashboard.

Available APIs

Ours Privacy provides access to the following AWS Location Services v2 APIs:

Autocomplete: Complete addresses and places as users type
Geocode: Convert addresses to geographic coordinates
GetPlace: Retrieve detailed information about a place by its ID
ReverseGeocode: Convert coordinates to human-readable addresses
SearchNearby: Find points of interest within a radius
SearchText: Search for locations using text queries
StaticMap: Generate static map images with optional scale display
Suggest: Get intelligent location suggestions based on context

For complete API documentation, including all parameters and response formats, refer to the AWS Location Services Places API documentation.

Autocomplete

The Autocomplete API provides real-time address and place suggestions as users type, offering predictive results from partial text input.

Endpoint

POST https://cdn.oursprivacy.com/location-services/v2/autocomplete?key=YOUR-API-KEY-HERE

Request Body

{
  "QueryText": "green bay",
  "BiasPosition": [-88.0198, 44.5192],
  "MaxResults": 5,
  "Filter": {
    "IncludeCountries": ["USA"]
  }
}

Example Request

const apiKey = "YOUR-API-KEY-HERE";
const endpoint = `https://cdn.oursprivacy.com/location-services/v2/autocomplete?key=${apiKey}`;

const requestBody = {
  QueryText: "green bay",
  BiasPosition: [-88.0198, 44.5192],
  MaxResults: 5,
  Filter: {
    IncludeCountries: ["USA"],
  },
};

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(requestBody),
});

const results = await response.json();

Documentation

For complete Autocomplete API documentation, see the AWS Autocomplete API reference.

Geocode

The Geocode API transforms text-based addresses and place names into latitude and longitude coordinates.

Endpoint

POST https://cdn.oursprivacy.com/location-services/v2/geocode?key=YOUR-API-KEY-HERE

Request Body

{
  "QueryText": "Times Square, New York, NY",
  "MaxResults": 3
}

Example Request

const apiKey = "YOUR-API-KEY-HERE";
const geocodeUrl = `https://cdn.oursprivacy.com/location-services/v2/geocode?key=${apiKey}`;

const geocodeResponse = await fetch(geocodeUrl, {
  method: "POST",
  headers: {
    "accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    QueryText: "Times Square, New York, NY",
    MaxResults: 3,
  }),
});

const locationData = await geocodeResponse.json();

Documentation

For complete Geocode API documentation, see the AWS Geocode API reference.

GetPlace

The GetPlace API retrieves detailed place information using a unique identifier. You can obtain a PlaceId from other location APIs such as Autocomplete, SearchText, or SearchNearby.

Endpoint

GET https://cdn.oursprivacy.com/location-services/v2/place/{PlaceId}?key=YOUR-API-KEY-HERE

Example Request

const apiKey = "YOUR-API-KEY-HERE";
const placeId = "PLACE_ID_HERE";
const placeUrl = `https://cdn.oursprivacy.com/location-services/v2/place/${placeId}?key=${apiKey}`;

const placeResponse = await fetch(placeUrl, {
  method: "GET",
  headers: {
    "accept": "application/json",
  },
});

const placeDetails = await placeResponse.json();

Documentation

For complete GetPlace API documentation, see the AWS GetPlace API reference.

ReverseGeocode

The ReverseGeocode API transforms latitude and longitude coordinates into formatted addresses and place names.

Endpoint

POST https://cdn.oursprivacy.com/location-services/v2/reverse-geocode?key=YOUR-API-KEY-HERE

Request Body

{
  "QueryPosition": [-73.9857, 40.7580],
  "MaxResults": 5
}

Example Request

const apiKey = "YOUR-API-KEY-HERE";
const reverseGeocodeUrl = `https://cdn.oursprivacy.com/location-services/v2/reverse-geocode?key=${apiKey}`;

const reverseGeocodeResponse = await fetch(reverseGeocodeUrl, {
  method: "POST",
  headers: {
    "accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    QueryPosition: [-73.9857, 40.7580],
    MaxResults: 5,
  }),
});

const addressData = await reverseGeocodeResponse.json();

Documentation

For complete ReverseGeocode API documentation, see the AWS ReverseGeocode API reference.

SearchNearby

The SearchNearby API discovers nearby points of interest within a specified distance from given coordinates. Results can be filtered by category, business type, cuisine, and other attributes.

Endpoint

POST https://cdn.oursprivacy.com/location-services/v2/search-nearby?key=YOUR-API-KEY-HERE

Request Body

{
  "QueryPosition": [-74.0060, 40.7128],
  "MaxResults": 15,
  "FilterCategories": ["Hospital", "Pharmacy"],
  "Distance": 3000
}

Example Request

const apiKey = "YOUR-API-KEY-HERE";
const nearbySearchUrl = `https://cdn.oursprivacy.com/location-services/v2/search-nearby?key=${apiKey}`;

const nearbyResults = await fetch(nearbySearchUrl, {
  method: "POST",
  headers: {
    "accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    QueryPosition: [-74.0060, 40.7128],
    MaxResults: 15,
    FilterCategories: ["Hospital", "Pharmacy"],
    Distance: 3000,
  }),
});

const nearbyPlaces = await nearbyResults.json();

Documentation

For complete SearchNearby API documentation, see the AWS SearchNearby developer guide.

SearchText

The SearchText API performs text-based searches to find locations and geocoding information. You can optionally use a query ID returned by the Suggest API to refine search results.

Endpoint

POST https://cdn.oursprivacy.com/location-services/v2/search-text?key=YOUR-API-KEY-HERE

Request Body

{
  "QueryText": "urgent care centers",
  "BiasPosition": [-88.0198, 44.5192],
  "MaxResults": 12
}

Example Request

const apiKey = "YOUR-API-KEY-HERE";
const textSearchUrl = `https://cdn.oursprivacy.com/location-services/v2/search-text?key=${apiKey}`;

const searchResponse = await fetch(textSearchUrl, {
  method: "POST",
  headers: {
    "accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    QueryText: "urgent care centers",
    BiasPosition: [-88.0198, 44.5192],
    MaxResults: 12,
  }),
});

const searchResults = await searchResponse.json();

Documentation

For complete SearchText API documentation, see the AWS SearchText developer guide.

StaticMap

The StaticMap API generates static map images that can be embedded in web pages, emails, or other applications. You can optionally add a scale indicator showing distance units (kilometers or miles) in the bottom-right corner of the map.

Endpoint

GET https://cdn.oursprivacy.com/location-services/v2/static/map?key=YOUR-API-KEY-HERE&style=Satellite&width=1024&height=1024&zoom=13.5&center=24.9189564,60.1645772&scale-unit=Kilometers

Query Parameters

key (required): Your API key
style (required): Map style - only Satellite is supported for static maps (other styles like standard-light, standard-dark are for dynamic maps only)
width (required): Image width in pixels
height (required): Image height in pixels
zoom (required): Zoom level (0-20)
center (required): Center point as longitude,latitude
scale-unit (optional): Scale indicator unit (Kilometers, Miles, KilometersMiles, MilesKilometers)

Example Request

Single unit scale:

const apiKey = "YOUR-API-KEY-HERE";
const staticMapUrl = `https://cdn.oursprivacy.com/location-services/v2/static/map?key=${apiKey}&style=Satellite&width=1024&height=1024&zoom=13.5&center=24.9189564,60.1645772&scale-unit=Kilometers`;

// Use in an img tag
<img src={staticMapUrl} alt="Map of Helsinki" />

Both units scale:

const apiKey = "YOUR-API-KEY-HERE";
const staticMapUrl = `https://cdn.oursprivacy.com/location-services/v2/static/map?key=${apiKey}&style=Satellite&width=1024&height=1024&zoom=14&center=24.9189564,60.1645772&scale-unit=KilometersMiles`;

<img src={staticMapUrl} alt="Map of Helsinki" />

Without scale:

const apiKey = "YOUR-API-KEY-HERE";
const staticMapUrl = `https://cdn.oursprivacy.com/location-services/v2/static/map?key=${apiKey}&style=Satellite&width=800&height=600&zoom=12&center=-88.0198,44.5192`;

<img src={staticMapUrl} alt="Map" />

Response

The API returns a static map image (PNG or JPEG format) with Content-Type: image/png or image/jpeg.

Scale Unit Options

Kilometers: Display scale in kilometers only
Miles: Display scale in miles only
KilometersMiles: Display both units with kilometers on top
MilesKilometers: Display both units with miles on top

Documentation

For complete StaticMap API documentation, see the AWS Static Map developer guide.

Suggest

The Suggest API generates contextual location recommendations and search suggestions based on user input, returning relevant places, points of interest, search terms, and category options.

Endpoint

POST https://cdn.oursprivacy.com/location-services/v2/suggest?key=YOUR-API-KEY-HERE

Request Body

{
  "QueryText": "medical",
  "BiasPosition": [-118.2437, 34.0522],
  "MaxResults": 8
}

Example Request

const apiKey = "YOUR-API-KEY-HERE";
const suggestUrl = `https://cdn.oursprivacy.com/location-services/v2/suggest?key=${apiKey}`;

const suggestions = await fetch(suggestUrl, {
  method: "POST",
  headers: {
    "accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    QueryText: "medical",
    BiasPosition: [-118.2437, 34.0522],
    MaxResults: 8,
  }),
});

const suggestionData = await suggestions.json();

Documentation

For complete Suggest API documentation, see the AWS Suggest developer guide.

Using Custom Domains

When using a custom domain, replace cdn.oursprivacy.com with your custom domain in all API endpoints:

https://metrics.yourdomain.com/location-services/v2/autocomplete?key=YOUR-API-KEY-HERE

Learn more about custom domains

Response Formats

Most APIs return JSON responses. Response formats match AWS Location Services API responses. The StaticMap API returns image data (PNG or JPEG). Refer to the AWS Location Services API documentation for complete response schema details.

Error Handling

API errors follow standard HTTP status codes:

200: Success
400: Bad Request (invalid parameters)
401: Unauthorized (invalid or missing API key)
403: Forbidden (insufficient permissions)
429: Too Many Requests (rate limit exceeded)
500: Internal Server Error

Error responses include a JSON body with error details:

{
  "error": {
    "code": "InvalidParameterException",
    "message": "Invalid parameter value"
  }
}

Rate Limits

Rate limits apply to all location APIs. Contact support@oursprivacy.com for information about rate limits for your account.

Example Resources

GitHub Repository: Complete code examples and implementation guides
Live Demo: Interactive demonstration of location APIs

Additional Resources

AWS Location Services Documentation: Complete API reference for all location services
Advanced Location Services: Build custom location experiences with map tiles, geocoding, and location APIs

Need Help?

If you have questions about location APIs or need assistance with integration, reach out to support@oursprivacy.com.

Location APIs Reference

Location APIs Reference

Base Endpoint

Custom Domain Support

Authentication

Available APIs

Autocomplete

Endpoint

Request Body

Example Request

Documentation

Geocode

Endpoint

Request Body

Example Request

Documentation

GetPlace

Endpoint

Example Request

Documentation

ReverseGeocode

Endpoint

Request Body

Example Request

Documentation

SearchNearby

Endpoint

Request Body

Example Request

Documentation

SearchText

Endpoint

Request Body

Example Request

Documentation

StaticMap

Endpoint

Query Parameters

Example Request

Response

Scale Unit Options

Documentation

Suggest

Endpoint

Request Body

Example Request

Documentation

Using Custom Domains

Response Formats

Error Handling

Rate Limits

Example Resources

Additional Resources

Need Help?

On this page