Resource Guide

Maps

Maps are images with the map image type. Browse them with the Images API, then use the Maps API to manage metadata and locations.

mapId is the image id returned by GET /v2/images?type=map, not the internal map record id.

Find map ids

Reference

List map-type images first. Use the returned image id as mapId for the Maps API.

curl "https://dev.niftyimages.com/v2/images?type=map" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Get a map

Reference

Fetch map metadata and location counts.

curl https://dev.niftyimages.com/v2/maps/{mapId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Update a map

Reference

Update a map's name, default search radius, or maximum result count. Only supplied fields are changed.

curl -X PATCH https://dev.niftyimages.com/v2/maps/{mapId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast Stores",
    "searchRadiusMiles": 25,
    "maxResults": 10
  }'

Search locations by address

Reference

Search locations by address text. Address search is cursor-paged.

curl "https://dev.niftyimages.com/v2/maps/{mapId}/locations?address=Market&limit=25" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Search locations by unique id

Reference

Find a location by the unique id you supplied when creating or updating it.

curl "https://dev.niftyimages.com/v2/maps/{mapId}/locations?uniqueId=sf-store" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Search locations by proximity

Reference

Find nearby locations with latitude, longitude, and an optional radius in miles.

curl "https://dev.niftyimages.com/v2/maps/{mapId}/locations?lat=37.7937&lng=-122.3965&radiusMiles=25" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Get a location

Reference

Fetch one location by id.

curl https://dev.niftyimages.com/v2/maps/{mapId}/locations/{locationId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Add a location by address

Reference

Add a location from an address. Address-based writes are queued for geocoding.

curl https://dev.niftyimages.com/v2/maps/{mapId}/locations \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "1 Market St, San Francisco, CA",
    "uniqueId": "sf-store",
    "properties": {
      "name": "San Francisco"
    }
  }'

Add a location by coordinates

Reference

Add a location when you already know its latitude and longitude.

curl https://dev.niftyimages.com/v2/maps/{mapId}/locations \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 37.7937,
    "longitude": -122.3965,
    "uniqueId": "sf-coordinates",
    "properties": {
      "name": "San Francisco"
    }
  }'

Update a location

Reference

Update any location field. Changing the address without explicit coordinates re-queues geocoding.

curl -X PATCH https://dev.niftyimages.com/v2/maps/{mapId}/locations/{locationId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "2 Market St, San Francisco, CA",
    "properties": {
      "name": "San Francisco Flagship"
    }
  }'

Delete a location

Reference

Hard-delete a location. The operation is idempotent and returns no content when the row is already gone.

curl -X DELETE https://dev.niftyimages.com/v2/maps/{mapId}/locations/{locationId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"