API Documentation

The Geo Insights marketing website exposes two public API endpoints for contact form submission and newsletter signup. Both endpoints accept JSON and return JSON responses.

OpenAPI Spec (JSON) llms.txt

Base URL

https://geo-insights.nl

All endpoints use HTTPS. Requests must include a Content-Type: application/json header. No authentication is required.

Rate Limiting

All API endpoints are rate limited per IP address. When a rate limit is exceeded, the API returns a 429 Too Many Requests response with the following headers:

Header	Description
`Retry-After`	Seconds until the rate limit resets
`RateLimit-Limit`	Maximum requests allowed in the window
`RateLimit-Remaining`	Requests remaining in the current window
`RateLimit-Reset`	Seconds until the current window resets
`RateLimit-Policy`	Rate limit policy description (e.g. `5;w=600`)

Error Responses

All errors return a JSON object with an error code, a human-readable message, and a resolution hint:

{
  "error": "MISSING_REQUIRED_FIELDS",
  "message": "Missing required fields",
  "resolution": "Provide name, organization, email and message in the JSON body."
}

POST /api/contact

POST Submit a contact form inquiry. Rate limited to 5 requests per 10 minutes per IP.

Request Body

Field	Type	Required	Description
`name`	string	required	Full name (max 200 chars)
`organization`	string	required	Organization name (max 200 chars)
`email`	string	required	Contact email address
`message`	string	required	Message body (max 5000 chars)
`topic`	string	optional	Subject or topic of the inquiry

Example Request

curl -X POST https://geo-insights.nl/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jan de Vries",
    "organization": "Gemeente Rotterdam",
    "email": "[email protected]",
    "topic": "pilot",
    "message": "Wij zijn geïnteresseerd in een pilot."
  }'

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": true }

Error Codes

Code	Status	Meaning
`METHOD_NOT_ALLOWED`	405	Only POST is accepted
`INVALID_BODY`	400	Request body is not valid JSON
`MISSING_REQUIRED_FIELDS`	400	name, organization, email or message is missing
`INVALID_EMAIL`	400	Email format is invalid
`FIELD_TOO_LONG`	400	A field exceeds its maximum length
`RATE_LIMITED`	429	Too many requests — wait and retry
`SERVER_NOT_CONFIGURED`	500	SMTP credentials not set
`SERVER_ERROR`	500	Unexpected server error

POST /api/newsletter

POST Subscribe to pilot update emails. Rate limited to 10 requests per 10 minutes per IP.

Request Body

Field	Type	Required	Description
`email`	string	required	Email address to subscribe
`firstName`	string	optional	First name (max 80 chars)
`lastName`	string	optional	Last name (max 80 chars)

Example Request

curl -X POST https://geo-insights.nl/api/newsletter \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jan",
    "lastName": "de Vries"
  }'

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": true }

Error Codes

Code	Status	Meaning
`METHOD_NOT_ALLOWED`	405	Only POST is accepted
`INVALID_BODY`	400	Request body is not valid JSON
`MISSING_EMAIL`	400	Email field is missing
`INVALID_EMAIL`	400	Email format is invalid
`RATE_LIMITED`	429	Too many requests — wait and retry
`SERVER_NOT_CONFIGURED`	500	Mailchimp credentials not set
`UPSTREAM_ERROR`	502	Mailchimp returned an error
`SERVER_ERROR`	500	Unexpected server error

Content Negotiation

The homepage supports Markdown content negotiation per the acceptmarkdown.com specification. Send Accept: text/markdown to receive a Markdown representation of the homepage content:

curl -H "Accept: text/markdown" https://geo-insights.nl/

The response includes Content-Type: text/markdown and Vary: Accept headers. Standard Accept: text/html requests return the full HTML page as usual.

Machine-Readable Resources

OpenAPI 3.1 specification — /openapi.json
Agent instructions — /llms.txt
Robots — /robots.txt
Sitemap — /sitemap.xml