https://github.com/1998code/mapshot
Apple MapKit Screenshot
https://github.com/1998code/mapshot
api apple map mapkit
Last synced: 6 months ago
JSON representation
Apple MapKit Screenshot
- Host: GitHub
- URL: https://github.com/1998code/mapshot
- Owner: 1998code
- License: mit
- Created: 2023-02-09T17:19:05.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-07-10T05:53:00.000Z (7 months ago)
- Last Synced: 2025-08-06T04:40:44.712Z (6 months ago)
- Topics: api, apple, map, mapkit
- Language: JavaScript
- Homepage: https://map-shot.vercel.app
- Size: 565 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# MapShot 🗺️
MapShot is an AI-powered map generation tool that creates beautiful Apple Maps snapshots using natural language descriptions. Simply describe the location and view you want, and MapShot will generate a high-quality map image for you.
## ✨ Features
- **Natural Language Input**: Describe any location in plain English
- **AI-Powered**: Uses Perplexity's Sonar models to understand your requests
- **Apple Maps Integration**: Generates high-quality map snapshots using Apple MapKit
- **Multiple View Types**: Standard, satellite, hybrid, and muted standard views
- **Customizable Options**: Control zoom levels, colors, and points of interest
- **Responsive Design**: Works seamlessly on desktop and mobile devices
- **Download & Share**: Save maps or copy URLs to share
## 🚀 Quick Start
### Prerequisites
- Node.js 16+ or Bun
- Apple Developer Account (for MapKit access)
- Perplexity API key
### Environment Variables
Create a `.env.local` file in the root directory:
```env
PERPLEXITY_API_KEY=your_perplexity_api_key
APPLE_MAP_PK=your_apple_mapkit_private_key
APPLE_TEAM_ID=your_apple_team_id
APPLE_KEY_ID=your_apple_key_id
```
### Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/MapShot.git
cd MapShot
# Install dependencies
npm install
# or
bun install
# Run the development server
npm run dev
# or
bun dev
```
Open [http://localhost:3000](http://localhost:3000) to view the application.
## 🎯 Usage
### Basic Examples
- "Show me Golden Gate Bridge"
- "Apple Park, Night Mode"
- "Times Square, standard view"
- "Central Park hybrid view"
- "Tokyo Tower night mode"
### Advanced Options
You can specify detailed parameters for precise control:
- **Zoom levels**: 3-20 (e.g., "zoom 15")
- **Map types**: standard, hybrid, satellite, mutedStandard
- **Color schemes**: light, dark
- **Points of Interest**: enabled/disabled (e.g., "poi disabled")
#### Example Advanced Query
```
"Manhattan, muted standard, zoom 10, poi disabled"
```
## 🛠️ Technical Stack
- **Frontend**: Next.js 13, React 18, Tailwind CSS
- **Backend**: Next.js API Routes
- **AI**: Perplexity Sonar API (multiple models available)
- **Maps**: Apple MapKit Snapshot API
- **Styling**: Tailwind CSS with custom components
- **Icons**: Font Awesome
## 📂 Project Structure
```
MapShot/
├── pages/
│ ├── api/
│ │ ├── ai.js # Perplexity AI integration
│ │ └── map.js # Apple Maps snapshot API
│ ├── _app.js # Next.js app configuration
│ ├── _document.js # HTML document structure
│ └── index.js # Main application page
├── public/
│ └── hero.jpg # Default background image
├── styles/
│ └── globals.css # Global styles
├── package.json
├── next.config.js
├── tailwind.config.js
└── README.md
```
## 🔧 API Reference
### AI Endpoint (`/api/ai`)
Processes natural language input and generates Apple Maps URL parameters.
**Method**: `POST`
**Body**:
```json
{
"input": "Golden Gate Bridge satellite view",
"model": "sonar-pro",
"user": "MapShot"
}
```
**Response**:
```json
{
"query": "Golden Gate Bridge satellite view",
"response": "size=640x640&scale=3&t=satellite¢er=Golden%20Gate%20Bridge&z=15"
}
```
### Map Endpoint (`/api/map`)
Generates and returns Apple Maps snapshot images.
**Method**: `GET`
**Query Parameters**: Apple MapKit snapshot parameters
**Response**: PNG image data
## 🎨 Customization
### Adding New AI Models
Edit the `aiModels` array in `pages/index.js`:
```javascript
const aiModels = [
{ id: 'sonar-pro', name: 'Sonar Pro', context: '200k' },
{ id: 'sonar', name: 'Sonar', context: '128k' },
// Add your model here
]
```
### Styling
The app uses Tailwind CSS for styling. Modify classes in the JSX or extend the configuration in `tailwind.config.js`.
### Map Specifications
- **Zoom Levels**: 3 (continent) to 20 (building detail)
- **Image Size**: 640x640px at 3x scale
- **Supported Languages**: Multi-language support via `lang` parameter
## 🔐 Security & Authentication
### Apple MapKit Setup
1. Create an Apple Developer Account
2. Generate a MapKit JS private key
3. Note your Team ID and Key ID
4. Add these to your environment variables
### Perplexity API Setup
1. Sign up for Perplexity API access
2. Generate an API key
3. Add to your environment variables
## 🚀 Deployment
### Vercel (Recommended)
1. Push your code to GitHub
2. Connect your repository to Vercel
3. Add environment variables in Vercel dashboard
4. Deploy automatically
### Other Platforms
The app can be deployed on any platform that supports Next.js:
- Netlify
- Railway
- Digital Ocean App Platform
- AWS Amplify
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Apple MapKit](https://developer.apple.com/maps/) for beautiful map rendering
- [Perplexity AI](https://www.perplexity.ai/) for intelligent natural language processing
- [Next.js](https://nextjs.org/) for the amazing React framework
- [Tailwind CSS](https://tailwindcss.com/) for utility-first styling
## 📞 Support
If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/1998code/MapShot/issues) page
2. Create a new issue with detailed information
3. Join our discussions