Places & Geocoding API

Search places, geocode addresses, and convert coordinates

v1
Overview

The Places API allows you to search for places, businesses, and points of interest worldwide. It returns rich metadata including ratings, categories, contact information, and location details.

Global Coverage

Search places worldwide with consistent data quality.

Rich Metadata

Get detailed information including ratings, categories, and contact details.

Base URL
https://api.geog.dev/v1/places
Search Places

Search for places by text query

GET /search

Search for places using a text query. Supports business names, addresses, categories, and more.

Query Parameters

q required

Search query text (e.g., "pizza near me", "Starbucks", "123 Main St")

lat optional

Latitude for location bias (-90 to 90)

lng optional

Longitude for location bias (-180 to 180)

limit optional

Maximum number of results (1-50, default: 10)

category optional

Filter by category (restaurant, hotel, gas_station, etc.)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.geog.dev/v1/places/search?q=coffee&lat=37.7749&lng=-122.4194&limit=5"

Example Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Blue Bottle Coffee",
        "category": "cafe",
        "address": "66 Mint St, San Francisco, CA 94103",
        "phone": "+1 (415) 495-3394",
        "website": "https://bluebottlecoffee.com",
        "rating": 4.2,
        "price_level": 2,
        "opening_hours": {
          "open_now": true,
          "periods": [
            {
              "open": { "day": 1, "time": "0600" },
              "close": { "day": 1, "time": "1900" }
            }
          ]
        }
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-122.4088, 37.7849]
      }
    }
  ],
  "attribution": "Data © geog"
}
Get Place Details

Get detailed information about a specific place

GET /{place_id}

Retrieve comprehensive details about a specific place using its unique identifier.

Path Parameters

place_id required

Unique identifier for the place (returned in search results)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.geog.dev/v1/places/place_12345"
Response Format

All responses return GeoJSON Feature Collections

Place Properties

Field
Type
Description
name string Place name
category string Place category
address string Formatted address
phone string Phone number
website string Website URL
rating number Rating (1-5)
price_level number Price level (1-4)
Error Responses
Status Code
Error
Description
400 Bad Request Invalid parameters
401 Unauthorized Invalid or missing API key
404 Not Found Place not found
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error
Geocoding

Convert addresses to coordinates and coordinates to addresses

The Places API includes geocoding capabilities for both forward geocoding (address to coordinates) and reverse geocoding (coordinates to address).

Forward Geocoding

Convert addresses to coordinates

GET /geocode/forward

Convert a text address or place name into geographic coordinates (latitude and longitude).

Query Parameters

q required

Address or place name to geocode

limit optional

Maximum number of results (1-10, default: 5)

country optional

Bias results to specific country (ISO 3166-1 alpha-2 code)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.geog.dev/v1/places/geocode/forward?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Example Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
        "country": "United States",
        "region": "California",
        "locality": "Mountain View",
        "postal_code": "94043",
        "confidence": 0.95,
        "match_type": "exact"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-122.0844, 37.4220]
      }
    }
  ],
  "attribution": "Data © geog"
}
Reverse Geocoding

Convert coordinates to addresses

GET /geocode/reverse

Convert geographic coordinates (latitude and longitude) into human-readable addresses.

Query Parameters

lat required

Latitude (-90 to 90)

lng required

Longitude (-180 to 180)

zoom optional

Zoom level for granularity (1-18, default: 18)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.geog.dev/v1/places/geocode/reverse?lat=37.4220&lng=-122.0844"

Example Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
        "house_number": "1600",
        "street": "Amphitheatre Parkway",
        "locality": "Mountain View",
        "region": "California",
        "country": "United States",
        "postal_code": "94043",
        "confidence": 0.98
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-122.0844, 37.4220]
      }
    }
  ],
  "attribution": "Data © geog"
}